Isikhokelo sabaphuhlisi

I-API yokuchonga iindwendwe

Chonga abasebenzisi abangeneyo ngekhowudi ukuze bangaze babone isicelo se-imeyile, kwaye iincoko zabo zinxulunyaniswe noqhagamshelwano ngokuzenzekelayo.

Nini ukusebenzisa oku

Ukuba iwebhusayithi yakho inabasebenzisi abangeneyo (ii-app ze-SaaS, iidashbhodi, iiphothali zamalungu), sele usazi ukuba bangoobani. Sebenzisa umyalelo othi identify ukudlulisela i-imeyile yabo kwiSonny ukuze bangafuneki baphinde bayifake.

  • Tsiba isicelo se-imeyile ngokupheleleyo kubasebenzisi abangeneyo
  • Nxulumanisa iincoko zechat nerekhodi yabo yoqhagamshelwano ngokuzenzekelayo
  • Bona igama ne-imeyile yondwendwe kwibhokisi yakho engenayo kwangoko
  • Qhubeka nembali kwiibrawuza nezixhobo ezahlukeneyo ngobuni obuqinisekisiweyo

Ukuqhubeka kwizixhobo ezahlukeneyo

Ubuni bendwendwe obuqinisekisiweyo

Ukuchonga okusisiseko nge-imeyile kulula, kodwa ibrawuza ingathi nayiphi na i-imeyile yeyayo. Ubuni obuqinisekisiweyo bongeza i-JWT ehlala ixesha elifutshane etyikitywe yiseva yakho. ISonny emva koko ingasebenzisa ngokukhuselekileyo oqhagamshelwano lomthengi njengomnini wembali yechat yewebhusayithi yakhe, ngoko iincoko ezifanayo zivela kwenye ibrawuza okanye isixhobo.

Ivaliwe

Okwesiqhelo. Akukho nto itshintshayo kwizinto ezifakiweyo esele zikhona okanye kwiindwendwe; imbali ihlala ibotshelelwe kwi-ID yondwendwe yebrawuza.

Ukuqinisekisa okunganyanzelekanga (kuyacetyiswa)

Ii-JWT ezisebenzayo zifumana imbali kwizixhobo ezahlukeneyo. Iindwendwe ezingenayo i-JWT zigcina amava esele ekhona angaziwayo okanye okuchonga nge-imeyile.

Funa ubungqina ukuze uchonge

Ichat engaziwayo isasebenza, kodwa ukubiza i-identify neempawu ezilungiselelweyo kufuna i-JWT etyikityiweyo esebenzayo.

Indlela yokuqinisekisa ayiwatshintshi amabala anyanzelekileyo angaphambi kwechat abe akhethwayo. Bona indlela nganye eyanelisa ngayo i-imeyile enyanzelekileyo phantsi kweenkcukacha ezinyanzelekileyo zangaphambi kwechat.

1. Yenza imfihlo yokusayina

Vula Izitishi → isitishi sakho → Ichat ephilayo, fumana Ubuni bendwendwe obukhuselekileyo, khetha indlela, uze wenze imfihlo. Umbhalo ocacileyo uboniswa kanye. Wugcine kumlawuli weemfihlo we-backend yakho njenge-SONNY_IDENTITY_SECRET. Ungaze ubeke imfihlo yokusayina kwikhowudi yebrawuza, kwikhowudi yokufaka, kwinto eguqukayo yendawo yoluntu, okanye kuvimba wakho wekhowudi yemvelaphi.

2. Yenza i-JWT ehlala ixesha elifutshane kwi-backend yakho

Sayina nge-HS256. ISonny ifuna i-user_id, email, iat ne-exp. I-user_id kufuneka ibe yi-ID ezinzileyo evela kwidatabase yakho, hayi idilesi ye-imeyile. Iithokheni zingahlala ubuninzi beeyure ezingama-24; imizuzu eli-15 ilungile njengokwesiqhelo. Iiwotshi zingahluka ukuya kuthi ga kwimizuzwana engama-60.

Ungafaka ne-object ye-traits etyikitywe yiseva yeenkcukacha zenkxaso ezithembekileyo ezifana ne-merchantName, subdomain, plan, platform ne-role. Amaxabiso eempawu kufuneka abe zii-string, amanani apheleleyo, ii-boolean okanye i-null. ISonny iwagcina kubuni boqhagamshelwano obuqinisekisiweyo bewebhusayithi. Iimpawu ezinikwa yibrawuza zihlala zingaqinisekiswanga kwaye azize zinyuselwe kwezi mpawu zityikityiweyo.

Node.js
import { SignJWT } from 'jose';

export async function createSonnyIdentityToken(user) {
  const secret = new TextEncoder().encode(process.env.SONNY_IDENTITY_SECRET);

  return new SignJWT({
    user_id: String(user.id),
    email: user.email,
    traits: {
      merchantName: user.merchant.name,
      subdomain: user.merchant.subdomain,
      plan: user.merchant.plan,
      platform: user.merchant.platform,
      role: user.role
    }
  })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('15m')
    .sign(secret);
}
Ruby
require 'jwt'

def sonny_identity_token(user)
  now = Time.now.to_i
  payload = {
    user_id: user.id.to_s,
    email: user.email,
    traits: {
      merchantName: user.merchant.name,
      subdomain: user.merchant.subdomain,
      plan: user.merchant.plan,
      platform: user.merchant.platform,
      role: user.role
    },
    iat: now,
    exp: now + 15 * 60
  }

  JWT.encode(payload, ENV.fetch('SONNY_IDENTITY_SECRET'), 'HS256')
end
Python
import os
from datetime import datetime, timedelta, timezone
import jwt

def sonny_identity_token(user):
    now = datetime.now(timezone.utc)
    return jwt.encode({
        "user_id": str(user.id),
        "email": user.email,
        "traits": {
            "merchantName": user.merchant.name,
            "subdomain": user.merchant.subdomain,
            "plan": user.merchant.plan,
            "platform": user.merchant.platform,
            "role": user.role,
        },
        "iat": now,
        "exp": now + timedelta(minutes=15),
    }, os.environ["SONNY_IDENTITY_SECRET"], algorithm="HS256")
PHP
use Firebase\JWT\JWT;

function sonnyIdentityToken($user): string {
    $now = time();
    return JWT::encode([
        'user_id' => (string) $user->id,
        'email' => $user->email,
        'traits' => [
            'merchantName' => $user->merchant->name,
            'subdomain' => $user->merchant->subdomain,
            'plan' => $user->merchant->plan,
            'platform' => $user->merchant->platform,
            'role' => $user->role,
        ],
        'iat' => $now,
        'exp' => $now + (15 * 60),
    ], $_ENV['SONNY_IDENTITY_SECRET'], 'HS256');
}

3. Dlulisela kuphela i-JWT kwiwijethi

Buyisa i-JWT ukusuka kwindawo yokugqibela ekhuselwe yiseshoni yesicelo sakho esiqhelekileyo. Biza i-identify phambi okanye emva kwe-init. Iwijethi igcina i-JWT enkumbulweni kuphela: ayize igcinwe kwi-localStorage, kwiikhuki okanye kwi-URL.

JavaScript
// Fetch a short-lived JWT from your authenticated backend.
// Your signing secret never reaches this code.
const { userJwt } = await fetch('/api/sonny-identity').then((res) => res.json());

sonny('identify', { userJwt });
sonny('init', { siteId: 'YOUR_SITE_ID' });

// Sonny asks for a fresh token after expiry or an emergency key change.
window.addEventListener('sonny:identity-required', async () => {
  const { userJwt } = await fetch('/api/sonny-identity').then((res) => res.json());
  sonny('identify', { userJwt });
});

Hlaziya, phuma kwaye utshintshe ngokukhuselekileyo

  • Hlaziya: hlaziya i-JWT phambi kokuba iphelelwe—malunga nemizuzu eli-10 kwithokheni yemizuzu eli-15—uze ubize i-sonny('identify', { userJwt }). Mamela ne-sonny:identity-required njengendlela yokugcina xa iphelelwa okanye xa isitshixo sokusayina sitshintsha.
  • Ukuphuma: biza i-sonny('reset'). Oku kulahla i-JWT esenkumbulweni, kucoca iseshoni yewijethi yebrawuza, kwaye kuqalisa undwendwe olutsha olungaziwayo.
  • Ukutshintsha iakhawunti: biza i-sonny('reset') yomsebenzisi A phambi kokulanda i-JWT yomsebenzisi B uze ubize i-sonny('identify', { userJwt }). Ungaze uthwale ithokheni yomsebenzisi omnye uyise kwenye iseshoni engeneyo.
  • Ukutshintsha okuqhelekileyo: ISonny yamkela imfihlo yangaphambili iiyure ezingama-24, ikunika ixesha lokuhlaziya yonke imeko ye-backend. Ukutshintsha okuqhelekileyo kwesibini kuvaliwe de kuphele olo thelekiso.
  • Imfihlo ekrokrelwa ukuba ivuzile: khetha Tshintsha kwangoko. Zombini izitshixo zokusayina ezindala ziyayeka ukungqinisisa izicelo ezintsha ngaxeshanye; iiwijethi eziqhagamshelweyo zicela iphepha elizibambileyo i-JWT entsha.
  • Vala ukuqinisekisa: ISonny ilahla iimfihlo zokusayina zangoku nezangaphambili kwaye inqamule iiwijethi eziqinisekisiweyo. Yenza imfihlo entsha phambi kokuphinda uvule ukuqinisekisa.

Ungquzulwano lobuni aludityaniswa ngokuzenzekelayo

Ukuba i-ID yomsebenzisi ezinzileyo ne-imeyile zalatha kubaqhagamshelwano beSonny abahlukeneyo, ukuqinisekisa kubuyisa ungquzulwano endaweni yokudibanisa iirekhodi zabathengi cwaka. Lungisa ithokheni okanye udibanise abaqhagamshelwano kwiSonny, uze uzame kwakhona.

Ichat enxulunyaniswe kuphela nge-imeyile engatyikitywanga yangaphambili ayithathwa ngokuzenzekelayo njengembali eqinisekisiweyo. Oku kuthintela i-imeyile enikwa yibrawuza ekuvuleni iincoko zomnye umthengi.

Ukungena kwiziko loncedo

Qhagamshela ukungena kwabathengi bakho esele kukho kumaphepha oncedo asingathiwe okanye akwidomeyini yakho. Sebenzisa imfihlo yokusayina yewebhusayithi efanayo ne-JWT ehlala ixesha elifutshane njengewijethi. Ukuchonga okusisiseko nge-imeyile nokungena kwabasebenzi beSonny akuniki ufikelelo lomfundi oqinisekisiweyo.

  1. Gqiba ukulungiselela ubuni bendwendwe obuqinisekisiweyo ngasentla kwesi sitishi. Vula Ukuqinisekisa okunganyanzelekanga okanye Funa ubungqina ukuze uchonge phantsi kwe-Izitishi → isitishi sakho → Ichat ephilayo.
  2. Yakha indawo yokugqibela eqinisekisiweyo kwi-app yakho ebuyisa i-{ "userJwt": "SIGNED_TOKEN" }. Yenza ithokheni kwiseva yakho ukusuka kumthengi ongeneyo neempawu ezithembekileyo; ungaze wamkele isicwangciso okanye indima ecelwe yibrawuza.
  3. Kwi-Izitishi → isitishi sakho → Iziko loncedo → Ukufikelela kwiziko loncedo, khetha Abathengi abaqinisekisiweyo naBaphulaphuli abangabathengi ukuba uyafuna. Faka iphepha lokungena le-app yakho njenge-I-URL yokungena kwabathengi uze ukhethe Gcina ukufikelela.
  4. Emva kokuba umthengi engene, qhuba utshintshiselwano olungezantsi, utshintshe i-YOUR_SLUG ngeDilesi yeziko loncedo. I-URL yokungena yodwa ayanele: i-app yakho kufuneka igqibe olu tshintshiselwano.
JavaScript
// Run after your application authenticates the customer.
// This endpoint must use the server's session and trusted customer traits.
const response = await fetch('/api/sonny-identity');
if (!response.ok) throw new Error('Unable to sign in to the help center');
const { userJwt } = await response.json();
const signIn = new URL('https://www.usesonny.com/help/YOUR_SLUG/auth');
signIn.searchParams.set('token', userJwt);
signIn.searchParams.set('return', '/help/YOUR_SLUG');
window.location.assign(signIn);

Kwidomeyini yakho, seta i-signIn ibe yi-https://help.example.com/auth uze ubuyele ku-/ okanye /articles/getting-started. Iindlela zokubuyela ezisingathiwe ziqala nge-/help/YOUR_SLUG. Iindawo zokubuyela kufuneka zihlale kumsingathi ofanayo.

Utshintshiselwano luseta ikhuki ekhuselekileyo, ye-HTTP-only kwaye luthumela kwenye indawo ukuze lususe ithokheni kwi-URL. Iseshoni yomfundi iphelelwa kunye ne-JWT, ukuya kuthi ga kwiiyure ezingama-24. Sebenzisa iithokheni ezihlala ixesha elifutshane kwaye uphephe ukubhala i-URL yotshintshiselwano kwiilog. I-JWT yeyolu tshintshiselwano lunye lokungena, hayi yamakhonkco amanqaku ekwabelwana ngawo.

Vavanya ukungena nofikelelo

  1. Tyelela iziko labucala ungangenanga. Landela iqhosha lalo lokungena, ngena kwi-app yakho, uze uqinisekise ukuba ubuyela kwiziko loncedo kwidomeyini efanayo esingathiwe okanye eyakho.
  2. Jonga inqaku elinye elivunyelweyo nelinye elingavunyelwanga xa ukhangela amaphepha, xa ukhangela nange-URL ethe ngqo. Umthengi ongaphandle kwabaphulaphuli beziko ubona umyalezo wofikelelo; inqaku elingavunyelwanga libuyisa ukuba alifumanekanga.
  3. Sebenzisa Phuma kwiziko loncedo uze uqinisekise ukuba umxholo wabucala uyanyamalala. Phinda ngomthengi oneempawu ezahlukeneyo.

Hlaziya uze uphume

Iwijethi ithumela i-JWT yayo yangoku ngokuzenzekelayo. Yihlaziye xa iSonny icela enye, uze ubize i-sonny('reset') xa umthengi wakho ephuma. Ubuni bewijethi nekhuki yeziko loncedo zahlukile: ukuseta kwakhona iwijethi akuyiphumi iseshoni yeziko loncedo esingathiwe.

Ukuze uphume kumaphepha asingathiwe, yiya ku-/help/YOUR_SLUG/auth/logout; kwidomeyini yakho, sebenzisa i-/auth/logout. Qhagamshela eso senzo kwinkqubo yokuphuma ye-app yakho ukuba ufuna ukuphelisa zombini iiseshoni. Iinkcukacha zokungena ezingasebenziyo okanye eziphelelweyo zinofikelelo lwendwendwe. Xa ukuqinisekiswa kobuni kuvaliwe, wonke umfundi unofikelelo lwendwendwe.

Xa iimpawu zomthengi zitshintsha, yenza i-JWT entsha uze uphinde uchonge kwiwijethi; phinda utshintshiselwano lokungena kumaphepha asingathiwe. Iikhuki zabafundi esele zikhona zigcina iimpawu zangaphambili ezityikityiweyo de ziphelelwe. Utshintsho lwemithetho yabaphulaphuli lusebenza kwisicelo esilandelayo.

Yenza abaphulaphuli, jonga ufikelelo kuqala, uze usombulule iingxaki zezithintelo

Ukuchonga nge-imeyile ayikokungqinisisa

Ifomu ye-imeyile enikwa yibrawuza iphucula iinkcukacha zenkxaso, kodwa ayimngqinisisi undwendwe. Undwendwe lungahlola luze luqhube i-JavaScript kwiphepha lalo, ngoko i-imeyile, igama neempawu ezilungiselelweyo azize zivule imbali yeSonny yomnye umthengi. Ubuni obuqinisekisiweyo bufuna i-JWT etyikitywe yiseva echazwe ngasentla. Gcina ugunyaziso lwezenzo kwimveliso yakho ngaphakathi kwesicelo sakho sokungena.

Xa ukuqinisekiswa kweendwendwe kuvuliwe, i-bheji ethi Kuqinisekisiwe kwibhokisi engenayo ithetha ukuba incoko inxulunyaniswe kusetyenziswa i-JWT etyikitywe yiseva. I-bheji ethi Akuqinisekiswanga ithetha ukuba akukho buni butyikitywe yiseva obungqinisise incoko. Naliphi na igama okanye i-imeyile ebonisiweyo yinkcukacha yenkxaso enikwe lundwendwe, ayibobungqina bobuni.

Imizekelo yekhowudi

Ukubiza okulula — dlulisela nje i-imeyile yomsebenzisi:

JavaScript
// Identify a logged-in user
sonny('identify', {
  email: 'jane@example.com'
});

Dlulisela negama lomsebenzisi, ukuze iiarhente zilibone kwibhokisi engenayo:

JavaScript
// Identify with full name
sonny('identify', {
  email: 'jane@example.com',
  name: 'Jane Smith'
});

Yongeza iinkcukacha zenkxaso eziluncedo ngexesha lokuchonga, uzihlaziye kamva, okanye ubukele ixabiso elitshintshayo ngelixa iphepha livuliwe:

JavaScript
// Identify with support context
sonny('identify', {
  email: 'jane@example.com',
  name: 'Jane Smith',
  attributes: {
    plan: 'starter',
    seats: 5,
    trial: true
  }
});

// Update only the values that changed
sonny('setAttributes', {
  plan: 'growth',
  seats: 8,
  trial: null // Clears this property
});

// Keep a changing value in sync (checks every 10 seconds)
sonny('watchAttributes', () => ({
  monthly_usage: window.currentUsage
}), { interval: 10000 });

Umzekelo opheleleyo nekhowudi ye-async. Qaphela ukuba i-identify ingabizwa phambi kwe-init — ubuni bubekwa emgceni kwaye buthunyelwe kwangoko xa iwijethi iqhagamshela:

HTML
<!-- Sonny widget snippet -->
<script>
  (function(w,d,s,o,f,js,fjs){
    w['Sonny']=o;w[o]=w[o]||function(){
    (w[o].q=w[o].q||[]).push(arguments)};
    js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
    js.id=o;js.src=f;js.async=1;fjs.parentNode.insertBefore(js,fjs);
  })(window,document,'script','sonny','https://www.usesonny.com/widget.js');

  // Identify before init — identity is queued and sent on connect
  sonny('identify', {
    email: 'jane@example.com',
    name: 'Jane Smith'
  });

  sonny('init', { siteId: 'YOUR_SITE_ID' });
</script>

Biza i-reset xa umsebenzisi ephuma ukuze ucoce ubuni bakhe uze uqalise iseshoni entsha:

JavaScript
// Reset on logout — clears identity and starts a fresh session
sonny('reset');

Isebenza njani

  1. 01

    Iwijethi iyalayisha kwaye iqhagamshele

    Iwijethi iqhagamshela kwiSonny kwaye ithumela nabuphi na ubuni obugciniweyo xa ijoyina.

  2. 02

    Ubuni buthunyelwa kwiseva

    ISonny ikhangela oqhagamshelwano onaloo imeyile kwindawo yakho yokusebenzela, kwaye imenze ukuba akakabikho.

  3. 03

    Iincoko ziyanxulunyaniswa

    Naziphi na iincoko ezinganxulunyaniswanga kwiseshoni yondwendwe yebrawuza yangoku zinxulunyaniswa noqhagamshelwano ochongiweyo. Ukuchonga akudibanisi imbali phakathi kweebrawuza okanye izixhobo.

  4. 04

    Isicelo se-imeyile siyatsitywa

    Ekubeni undwendwe sele luchongiwe, isicelo se-imeyile esikwiwijethi siyacinywa — akukho kuphazanyiswa komsebenzisi.

Imithetho yeempawu ezilungiselelweyo

  • Thumela iimpawu ezingaphezu kwe-50 ngokubiza ngakunye.
  • Ixabiso lingaba yi-string, inani, i-boolean okanye i-null. Ii-string zinomda wabalinganiswa abayi-1000. Dlulisela i-null okanye i-string engenanto ukuze ucoce ixabiso eligciniweyo.
  • Izitshixo kufuneka ziqale ngonobumba kwaye ziqulathe oonobumba, amanani nemigca engezantsi kuphela, ubuninzi babalinganiswa abangama-64.
  • Ezi zitshixo zigciniwe kwaye ziyatyeshelwa: email, name, id, phone, createdAt, updatedAt.

Isalathiso se-API

sonny('identify', { email, name?, attributes? })
Ichonga undwendwe lwangoku. Iseta i-imeyile negama ukuba likhona, itsiba isicelo se-imeyile, kwaye ithumela ubuni kwiseva. Ingabizwa phambi okanye emva kwe-init.
  • emailstringIdilesi ye-imeyile yondwendwe
  • namestring?Igama elibonakalayo lendwendwe
  • attributesobject?Iimpawu ezilungiselelweyo zokuncamathisela kuqhagamshelwano (jonga isikhokelo sokulungiselela iwijethi ngemithetho yezitshixo namaxabiso)
sonny('identify', { userJwt, name?, attributes? })
Ichonga ngokukhuselekileyo umthengi wangoku ongeneyo ukusuka kwi-JWT eyenziwe yiseva. Ithokheni ihlala enkumbulweni kwaye ithunyelwa kuphela kwizicelo eziqinisekisiweyo okanye kwimithwalo ye-socket.
  • userJwtstringI-JWT entsha ye-HS256 eyenziwe yi-backend yakho eqinisekisiweyo
  • namestring?Igama elibonakalayo lendwendwe
  • attributesobject?Iimpawu ezilungiselelweyo zokuncamathisela kuqhagamshelwano oluqinisekisiweyo
sonny('setAttributes', { ... })
Ihlaziya iimpawu ezilungiselelweyo zondwendwe oluchongiweyo. Kuthunyelwa amaxabiso atshintshileyo kuphela. Ukuba undwendwe alukachongwa, uhlaziyo luyalinda kwaye luthunyelwe emva kokuba i-identify isebenze.
  • attributesobjectIzibini zesitshixo nexabiso zokuseta. Dlulisela i-null njengexabiso ukuze ucoce impawu.
sonny('watchAttributes', getter, { interval? })
Ibiza umsebenzi wakho wokufumana ngexesha elithile kwaye ivumelanise naziphi na iimpawu ezitshintshileyo ngokuzenzekelayo. Iluncedo xa amaxabiso afana nesicwangciso okanye ukusetyenziswa etshintsha ngelixa iphepha livuliwe.
  • getterfunctionUmsebenzi obuyisa i-object yeempawu zangoku
  • intervalnumber?Ijonga kangaphi, ngee-millisecond. Okwesiqhelo yi-10000, ubuncinane yi-2000.
sonny('reset')
Icoca i-ID yewijethi yebrawuza yangoku, i-imeyile, igama nembali yeencoko yasekhaya, emva koko iqalise iseshoni entsha yondwendwe. Ayimcimi oqhagamshelwano okanye iimpawu zakhe ezigciniweyo kwiSonny. Yisebenzise xa kuphunywa.

Ufuna uncedo?

Jonga isikhokelo sokulungiselela iwijethi okanye uqhagamshelane neqela lethu.

Isikhokelo sokulungiselela iwijethiQhagamshelana nathi

Amaxwebhu anxulumeneyo

Bona ukuba iSonny inceda njani