تحديد هوية المستخدمين
كل زائر هو ضيف افتراضيًا. عندما يسجّل المستخدم دخوله إلى موقعكم أو تطبيقكم، يمكن لخادمكم توقيع رمز هوية قصير له، ليعرف Kavchat من هو.
لماذا تحددون هوية المستخدمين
- معرّف المستخدم لديكم في كل تذكرة. تُربط المحادثات والتذاكر بمعرّف المستخدم لديكم (
userIdفي التذكرة)، ليعرف فريقكم الحساب الذي تتبع له. - لا حاجة لإدخال بيانات الاتصال. يجب على الضيف ترك بريد إلكتروني أو رقم هاتف في نموذج التذكرة. أما المستخدم المعروف الهوية فليس ملزمًا بذلك.
- مستخدمو الاختبار. عندما يكون الجمهور المستهدف "مستخدمي الاختبار"، لا يظهر البوت إلا للمستخدمين الذين ترد أرقام هواتفهم في قائمة مستخدمي الاختبار لديكم. ويتعرّف عليهم Kavchat من رقم الهاتف الموجود في الرمز.
- تحية شخصية. يُستبدل
{name}في خطوة من السيناريو بالاسم الأول للمستخدم.
الرمز
رمز الهوية هو JWT قياسي يُنشأ على خادمكم:
- الخوارزمية هي
HS256. والمفتاح هو مفتاحكم السري: السلسلة الكاملةsk_live_...، على شكل بايتات بترميز UTF-8. - ترسله الصفحة أو التطبيق في الترويسة
Authorization: Bearer <token>مع كل استدعاء إلى Kavchat. - لا توقّعوا الرموز أبدًا في المتصفح أو التطبيق. يبقى المفتاح السري على خادمكم.
| الحقل | مطلوب | الوصف |
|---|---|---|
sub | نعم | معرّف المستخدم لديكم، من 1 إلى 128 حرفًا. |
exp | نعم | وقت انتهاء الصلاحية، بحد أقصى 30 يومًا من الآن. المدة الافتراضية في حزم التطوير هي 7 أيام. |
phone | لا | بتنسيق E.164 (+972501234567) أو رقم محلي. يُستخدم للتعرّف على مستخدمي الاختبار. |
name | لا | يظهر في التحية ويُملأ مسبقًا في نموذج التذكرة. |
email | لا | يُملأ مسبقًا في نموذج التذكرة. |
أنشئوا رمزًا جديدًا عندما يسجّل المستخدم دخوله، ثم أنشئوا آخر قبل انتهاء صلاحية الرمز السابق. مدة صلاحية قصيرة، لبضعة أيام، خيار افتراضي مناسب.
تثبيت حزمة تطوير للخادم
تُنشئ حزم تطوير الخادم الرمز نيابةً عنكم، وتتحقق من صحة webhook، وتستدعي API الخادم. ولا تعتمد على أي مكتبات خارج المكتبة القياسية لكل لغة (في Java تعتمد على Jackson).
yarn add @kavchat/node
# or: npm install @kavchat/nodepip install kavchatcomposer require kavchat/kavchat-php<!-- Maven, served by JitPack. Gradle: maven("https://jitpack.io") and implementation("com.kavchat:kavchat-java:0.0.11") -->
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
<dependency>
<groupId>com.kavchat</groupId>
<artifactId>kavchat-java</artifactId>
<version>0.0.11</version>
</dependency>dotnet add package Kavchatgo get kavchat.com/kavchat-go# Gemfile
gem "kavchat"إنشاء رمز
import { Kavchat } from '@kavchat/node';
const kavchat = new Kavchat(process.env.KAVCHAT_SECRET_KEY!);
const token = kavchat.createUserToken({
userId: 'user_123', // required, 1 to 128 characters
phone: '+972501234567', // optional
name: 'Dana', // optional
email: 'dana@example.com', // optional
expiresIn: 7 * 24 * 3600, // seconds, default 7 days, at most 30 days
});
// Send the token to your page or app and pass it to the Kavchat widget or SDK.import os
from kavchat import Kavchat
kavchat = Kavchat(os.environ["KAVCHAT_SECRET_KEY"])
token = kavchat.create_user_token(
"user_123", # required, 1 to 128 characters
phone="+972501234567",
name="Dana",
email="dana@example.com",
expires_in=7 * 24 * 3600, # seconds, default 7 days, at most 30 days
)use Kavchat\Kavchat;
$kavchat = new Kavchat(getenv('KAVCHAT_SECRET_KEY'));
$token = $kavchat->createUserToken(
'user_123', // required, 1 to 128 characters
phone: '+972501234567',
name: 'Dana',
email: 'dana@example.com',
expiresIn: 7 * 24 * 3600 // seconds, default 7 days, at most 30 days
);KavchatClient kavchat = KavchatClient.builder(System.getenv("KAVCHAT_SECRET_KEY")).build();
String token = kavchat.createUserToken(UserTokenOptions.builder("user_123")
.phone("+972501234567")
.name("Dana")
.email("dana@example.com")
.expiresIn(Duration.ofDays(7)) // default 7 days, at most 30 days
.build());using Kavchat;
using var kavchat = new KavchatClient(Environment.GetEnvironmentVariable("KAVCHAT_SECRET_KEY")!);
var token = kavchat.CreateUserToken(new UserTokenOptions
{
UserId = "user_123", // required, 1 to 128 characters
Phone = "+972501234567",
Name = "Dana",
Email = "dana@example.com",
ExpiresIn = TimeSpan.FromDays(7), // default 7 days, at most 30 days
});import kavchat "kavchat.com/kavchat-go"
client := kavchat.New(os.Getenv("KAVCHAT_SECRET_KEY"))
token, err := client.CreateUserToken(kavchat.UserToken{
UserID: "user_123", // required, 1 to 128 characters
Phone: "+972501234567",
Name: "Dana",
Email: "dana@example.com",
ExpiresIn: 7 * 24 * time.Hour, // zero means 7 days; at most 30 days
})require "kavchat"
kavchat = Kavchat::Client.new(ENV.fetch("KAVCHAT_SECRET_KEY"))
token = kavchat.create_user_token(
user_id: "user_123", # required, 1 to 128 characters
phone: "+972501234567",
name: "Dana",
email: "dana@example.com",
expires_in: 7 * 24 * 3600 # seconds, default 7 days, at most 30 days
)تتضمن كل حزمة أيضًا نسخة مستقلة تقبل المفتاح السري كوسيط أول، مثل createUserToken(secretKey, options) في Node.js. إذا كان معرّف المستخدم فارغًا أو أطول من المسموح، أو كانت مدة الصلاحية خارج النطاق من ثانية واحدة إلى 30 يومًا، فسينتج خطأ في الوسيط.
بدون حزمة تطوير
يمكنكم استخدام أي مكتبة JWT. هذه هي الأمثلة نفسها التي تعرضها لوحة التحكم في صفحة التثبيت:
import jwt from 'jsonwebtoken';
// On your server only. Never send the secret key to the browser.
const token = jwt.sign(
{ sub: user.id, phone: user.phone, name: user.firstName, email: user.email },
process.env.KAVCHAT_SECRET_KEY, // sk_live_...
{ algorithm: 'HS256', expiresIn: '7d' },
);import jwt, time, os
token = jwt.encode(
{"sub": user.id, "phone": user.phone, "name": user.first_name,
"exp": int(time.time()) + 7 * 24 * 3600},
os.environ["KAVCHAT_SECRET_KEY"], # sk_live_...
algorithm="HS256",
)use Firebase\JWT\JWT;
$token = JWT::encode([
'sub' => $user->id,
'phone' => $user->phone,
'name' => $user->first_name,
'exp' => time() + 7 * 24 * 3600,
], getenv('KAVCHAT_SECRET_KEY'), 'HS256'); // sk_live_...تمرير الرمز إلى الدردشة
أرسلوا الرمز إلى الصفحة أو التطبيق، مثلًا مع الاستجابة لاستدعاء تسجيل الدخول، ثم مرّروه إلى أداة الدردشة أو حزمة التطوير. يؤدي تبديل المستخدم إلى إعادة تحميل البوت وبدء محادثة جديدة.
// at page load, with a token your server created for the signed-in user
Kavchat.init({ publicKey: 'pk_live_...', userToken: token, userName: 'Dana' });
// later, after login or logout
Kavchat.setUser({ token, name: 'Dana' });
Kavchat.setUser(null);<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>await kavchat.setUser(token: jwt, name: 'Dana'); // after login
await kavchat.setUser(token: null); // after logoutKavchat.setUser(token: identityToken, name: "Dana") // after login
Kavchat.setUser(token: nil) // after logoutKavchat.setUser(token = identityToken, name = "Dana") // after login
Kavchat.setUser(token = null) // after logoutمزيد من التفاصيل في كل دليل: الموقع الإلكتروني، React Native، Flutter، iOS، Android.
عند رفض الرمز
يُرفض الرمز إذا انتهت صلاحيته، أو وُقّع بمفتاح آخر، أو كان يفتقد sub، مع حالة HTTP 401 ورمز الخطأ identity_invalid. تحققوا من ساعة الخادم والمفتاح، ومن أن exp لا يتجاوز 30 يومًا من الآن.