قائمة الأدلة

تحديد هوية المستخدمين

كل زائر هو ضيف افتراضيًا. عندما يسجّل المستخدم دخوله إلى موقعكم أو تطبيقكم، يمكن لخادمكم توقيع رمز هوية قصير له، ليعرف 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).

Node.js
yarn add @kavchat/node
# or: npm install @kavchat/node
Python
pip install kavchat
PHP
composer require kavchat/kavchat-php
Java
<!-- 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>
.NET
dotnet add package Kavchat
Go
go get kavchat.com/kavchat-go
Ruby
# Gemfile
gem "kavchat"

إنشاء رمز

Node.js
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.
Python
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
)
PHP
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
);
Java
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());
.NET
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
});
Go
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
})
Ruby
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. هذه هي الأمثلة نفسها التي تعرضها لوحة التحكم في صفحة التثبيت:

Node.js
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' },
);
Python
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",
)
PHP
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_...

تمرير الرمز إلى الدردشة

أرسلوا الرمز إلى الصفحة أو التطبيق، مثلًا مع الاستجابة لاستدعاء تسجيل الدخول، ثم مرّروه إلى أداة الدردشة أو حزمة التطوير. يؤدي تبديل المستخدم إلى إعادة تحميل البوت وبدء محادثة جديدة.

Website
// 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);
React Native
<KavchatProvider publicKey="pk_live_..." userToken={session?.kavchatToken} userName={session?.firstName}>
Flutter
await kavchat.setUser(token: jwt, name: 'Dana'); // after login
await kavchat.setUser(token: null);              // after logout
iOS
Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // after logout
Android
Kavchat.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 يومًا من الآن.