זיהוי משתמשים
כברירת מחדל כל מבקר הוא אורח. כשמשתמש מחובר לאתר או לאפליקציה שלכם, השרת יכול לחתום עבורו טוקן זהות קצר, וכך 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 וקוראות ל-Server 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 יום קדימה.