Umhlahlandlela wonjiniyela

I-API yokuhlonza izivakashi

Hlonza abasebenzisi abangenile ngokohlelo ukuze bangaze babone isicelo se-imeyili, futhi izingxoxo zabo zixhunywe ngokuzenzakalelayo koxhumana naye.

Nini ukusebenzisa lokhu

Uma iwebhusayithi yakho inabasebenzisi abangenile (izinhlelo ze-SaaS, amadeshibhodi, amaphothali amalungu), usuvele wazi ukuthi bangobani. Sebenzisa umyalo we-identify ukuze udlulisele i-imeyili yabo ku-Sonny ukuze bangadingi ukuyifaka futhi.

Yeqa isicelo se-imeyili ngokuphelele kubasebenzisi abangenile
Xhuma ngokuzenzakalelayo izingxoxo zengxoxo nerekhodi labo loxhumana naye
Bona igama ne-imeyili yesivakashi ku-inbox yakho ngokushesha
Qhubeka nomlando kuzo zonke iziphequluli namadivayisi ngobunikazi obuqinisekisiwe

Ukuqhubeka kuwo wonke amadivayisi

Ubunikazi besivakashi obuqinisekisiwe

Ukuhlonza okuyisisekelo nge-imeyili kulula, kodwa isiphequluli singathi noma iyiphi i-imeyili. Ubunikazi obuqinisekisiwe bengeza i-JWT yesikhashana esayinwe yiseva yakho. I-Sonny ingabe isisebenzisa ngokuphephile oxhumana naye wekhasimende njengomnikazi womlando wakhe wengxoxo yewebhusayithi, ukuze izingxoxo ezifanayo zivele kwesinye isiphequluli noma kwenye idivayisi.

Kuvaliwe

Okuzenzakalelayo. Akukho okushintshayo kumakhodi afakiwe akhona noma kuzivakashi; umlando uhlala uboshelwe ku-ID yesivakashi yesiphequluli.

Ukuqinisekisa okungaphoqelekile (kunconyiwe)

Ama-JWT avumelekile athola umlando kuwo wonke amadivayisi. Izivakashi ezingenayo i-JWT zigcina okuhlangenwe nakho okukhona kokungaziwa noma kokuhlonza nge-imeyili.

Dinga ubufakazi ukuze uhlonze

Ingxoxo engaziwa isasebenza, kodwa izikholi ze-identify nezezimfanelo zangokwezifiso zidinga i-JWT esayiniwe evumelekile.

Imodi yokuqinisekisa ayenzi izinkambu ezidingekayo zangaphambi kwengxoxo zingaphoqeleki. Bona ukuthi imodi ngayinye ihlangabezana kanjani ne-imeyili edingekayo ngaphansi kwe-imininingwane edingekayo yangaphambi kwengxoxo.

1. Yakha imfihlo yokusayina

Vula i-Iziteshi → isiteshi sakho → Ingxoxo ebukhoma, thola i-Ubunikazi besivakashi obuvikelekile, khetha imodi, bese wakha imfihlo. Umbhalo ocacile uboniswa kanye kuphela. Wulondoloze kumphathi wezimfihlo we-backend yakho njenge-SONNY_IDENTITY_SECRET. Ungalokothi ufake imfihlo yokusayina kukhodi yesiphequluli, kusnippet sokufaka, kokuguquguqukayo kwemvelo okusobala, noma endaweni yakho yekhodi yomthombo.

2. Yakha i-JWT yesikhashana ku-backend yakho

Sayina nge-HS256. I-Sonny idinga i-user_id, i-email, i-iat, ne-exp. I-user_id kufanele ibe yi-ID ezinzile evela kusizindalwazi sakho, hhayi ikheli le-imeyili. Ama-token angahlala amahora angu-24 ubuningi; imizuzu engu-15 iyinani elizenzakalelayo elihle. Amawashi angahluka ngemizuzwana efika ku-60.

Ungafaka nento ye-traits esayinwe yiseva yomongo wosizo othembekile onjenge-merchantName, subdomain, plan, platform, ne-role. Amanani ezici kufanele abe yimibhalo, izinombolo ezilinganiselwe, ama-boolean, noma i-null. I-Sonny iwagcina kubunikazi boxhumana naye obuqinisekisiwe obukhawulelwe kuwebhusayithi. Izimfanelo ezihlinzekwa yisiphequluli zihlala zingaqinisekisiwe futhi azilokothi zikhushulelwe kulezi zici ezisayiniwe.

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 i-JWT kuphela ku-widget

Buyisa i-JWT kusuka ku-endpoint evikelwe iseshini yakho evamile yohlelo lokusebenza. Biza i-identify ngaphambi noma ngemuva kwe-init. I-widget igcina i-JWT enkumbulweni kuphela: ayilokothi ilondolozwe ku-localStorage, kuma-cookie, noma ku-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 });
});

Vuselela, phuma, futhi ushintshanise ngokuphephile

Vuselela: vuselela i-JWT ngaphambi kokuba iphelelwe yisikhathi — cishe ngemizuzu engu-10 ku-token yemizuzu engu-15 — bese ubiza i-sonny('identify', { userJwt }). Lalela futhi i-sonny:identity-required njengesizinda sokuphelelwa yisikhathi noma ushintsho lokhiye wokusayina.
Phuma: biza i-sonny('reset'). Lokhu kulahla i-JWT esenkumbulweni, kusule iseshini ye-widget yesiphequluli, futhi kuqale isivakashi esisha esingaziwa.
Ukushintsha i-akhawunti: biza i-sonny('reset') yomsebenzisi A ngaphambi kokulanda i-JWT yomsebenzisi B nokubiza i-sonny('identify', { userJwt }). Ungalokothi uyise i-token yomsebenzisi oyedwa kwenye iseshini engenile.
Ukushintshanisa okujwayelekile: I-Sonny yamukela imfihlo yangaphambilini amahora angu-24, ikunika isikhathi sokubuyekeza zonke izibonelo ze-backend yakho. Ukushintshanisa kwesibili okujwayelekile kuvinjiwe kuze kuphele lokho kugqagqana.
Ukuvuza kwemfihlo okusolwayo: khetha i-Shintsha ngokushesha. Bobabili okhiye bokusayina abadala bayayeka ukuqinisekisa izicelo ezintsha ngasikhathi sinye; ama-widget axhunyiwe acela ikhasi elisingathayo i-JWT entsha.
Vala ukuqinisekisa: I-Sonny ilahla izimfihlo zokusayina zamanje nezangaphambilini futhi inqamule ama-widget aqinisekisiwe. Yakha imfihlo entsha ngaphambi kokuvula ukuqinisekisa futhi.

Ukungqubuzana kobunikazi akuhlanganiswa ngokuzenzakalelayo

Uma i-ID yomsebenzisi ezinzile ne-imeyili kukhomba koxhumana nabo be-Sonny abahlukene, ukuqinisekisa kubuyisa ukungqubuzana esikhundleni sokuhlanganisa amarekhodi amakhasimende buthule. Lungisa i-token noma uhlanganise oxhumana nabo ku-Sonny, bese uzama futhi.

Ingxoxo exhunywe kuphela nge-imeyili yangaphambilini engasayiniwe ayithathwa ngokuzenzakalelayo njengomlando oqinisekisiwe. Lokhu kuvimbela i-imeyili ehlinzekwe yisiphequluli ekuvuleni izingxoxo zenye ikhasimende.

Ukungena esikhungweni sosizo

Xhuma ukungena kwamakhasimende akho okukhona namakhasi osizo asingathiwe noma asesizindeni sangokwezifiso. Sebenzisa imfihlo efanayo yokusayina yewebhusayithi ne-JWT yesikhashana efana neye-widget. Ukuhlonza okuyisisekelo nge-imeyili nokungena kwabasebenzi be-Sonny akunikezi ukufinyelela komfundi okuqinisekisiwe.

Qedela ukusetha ubunikazi besivakashi obuqinisekisiwe ngenhla kulesi siteshi. Vula i-Ukuqinisekisa okungaphoqelekile noma i-Dinga ubufakazi ukuze uhlonze ngaphansi kwe-Iziteshi → isiteshi sakho → Ingxoxo ebukhoma.
Yenza i-endpoint eqinisekisiwe kuhlelo lwakho lokusebenza ebuyisa i-{ "userJwt": "SIGNED_TOKEN" }. Yakha i-token kuseva yakho kusuka kukhasimende elingenile nasezicini ezithembekile; ungalokothi wamukele uhlelo noma indima eceliwe esuka esiphequlini.
Ku-Iziteshi → isiteshi sakho → Isikhungo sosizo → Ukufinyelela kwesikhungo sosizo, khetha i-Amakhasimende aqinisekisiwe kanye ne-Izethameli zamakhasimende okungaphoqelekile. Faka ikhasi lokungena lohlelo lwakho lokusebenza njenge-I-URL yokungena kwekhasimende bese ukhetha i-Londoloza ukufinyelela.
Ngemuva kokuthi ikhasimende lingene, qhuba ukushintshana okungezansi, ushintshe i-YOUR_SLUG nge-Ikheli lesikhungo sosizo. I-URL yokungena iyodwa ayanele: uhlelo lwakho lokusebenza kufanele luqedele lokhu kushintshana.

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);

Esizindeni sangokwezifiso, setha i-signIn ibe yi-https://help.example.com/auth bese ubuyela ku-/ noma ku-/articles/getting-started. Izindlela zokubuyela ezisingathiwe ziqala nge-/help/YOUR_SLUG. Izindawo zokubuyela kufanele zihlale kumsingathi ofanayo.

Ukushintshana kusetha i-cookie evikelekile, ye-HTTP kuphela, bese kuqondisa kabusha ukuze kususwe i-token ku-URL. Iseshini yomfundi iphelelwa yisikhathi ne-JWT, kuze kube amahora angu-24. Sebenzisa ama-token esikhashana futhi ugweme ukuloga i-URL yokushintshana. I-JWT ingeyalokhu kushintshana kokungena okukodwa, hhayi ezixhumanisini zama-athikili ezabiwe.

Hlola ukungena nokufinyelela

Vakashela isikhungo esiyimfihlo ungangenile. Landela inkinobho yaso yokungena, ngena kuhlelo lwakho lokusebenza, bese uqinisekisa ukuthi ubuyela esikhungweni sosizo esizindeni esifanayo esisingathiwe noma sangokwezifiso.
Hlola i-athikili eyodwa evunyelwe neyodwa enqatshelwe ekuphequluleni, ekuseshweni, nange-URL eqondile. Ikhasimende elingaphandle kwezethameli zesikhungo libona umlayezo wokufinyelela; i-athikili enqatshelwe ibuyisa okuthi ayitholakali.
Sebenzisa i-Phuma esikhungweni sosizo bese uqinisekisa ukuthi okuqukethwe okuyimfihlo kuyanyamalala. Phinda nekhasimende elinezici ezihlukile.

Vuselela futhi uphume

I-widget ithumela i-JWT yayo yamanje ngokuzenzakalelayo. Yivuselele lapho i-Sonny iyicela, futhi ubize i-sonny('reset') lapho ikhasimende lakho liphuma. Ubunikazi be-widget ne-cookie yesikhungo sosizo kuhlukile: ukusetha kabusha i-widget akuyiphumi iseshini yesikhungo sosizo esisingathiwe.

Ukuze uphume emakhasini asingathiwe, iya ku-/help/YOUR_SLUG/auth/logout; esizindeni sakho sangokwezifiso, sebenzisa i-/auth/logout. Xhuma leso senzo nokugeleza kokuphuma kohlelo lwakho lokusebenza uma udinga ukuqeda womabili amaseshini. Imininingwane yokungena engavumelekile noma ephelelwe yisikhathi inokufinyelela kwesivakashi. Uma ukuqinisekiswa kobunikazi kuvaliwe, wonke umfundi unokufinyelela kwesivakashi.

Uma izici zekhasimende zishintsha, yakha i-JWT entsha bese uhlonza futhi ku-widget; phinda ukushintshana kokungena kumakhasi asingathiwe. Ama-cookie abafundi akhona agcina izici ezisayiniwe zangaphambilini kuze kuphelelwe yisikhathi. Izinguquko zemithetho yezethameli zisebenza esicelweni esilandelayo.

Dala izethameli, buka kuqala ukufinyelela, futhi uxazulule izinkinga zemikhawulo

Ukuhlonza nge-imeyili akukhona ukuqinisekisa ubunikazi

Ifomu le-imeyili elihlinzekwa yisiphequluli lithuthukisa umongo wosizo, kodwa aliqinisekisi ubunikazi besivakashi. Isivakashi singahlola futhi siqhube i-JavaScript ekhasini laso, ngakho i-imeyili, igama, nezimfanelo zangokwezifiso azilokothi zivule umlando we-Sonny wenye ikhasimende. Ubunikazi obuqinisekisiwe budinga i-JWT esayinwe yiseva echazwe ngenhla. Gcina ukugunyazwa kwezenzo emkhiqizweni wakho ngaphakathi kohlelo lwakho lokusebenza olungenile.

Uma ukuqinisekiswa kwezivakashi kuvuliwe, ibheji elithi Kuqinisekisiwe ku-inbox lisho ukuthi ingxoxo ixhunywe kusetshenziswa i-JWT esayinwe yiseva. Ibheji elithi Akuqinisekisiwe lisho ukuthi abukho ubunikazi obusayinwe yiseva obuqinisekise ingxoxo. Noma yiliphi igama noma i-imeyili eboniswayo kungumongo wosizo ohlinzekwe yisivakashi, hhayi ubufakazi bobunikazi.

Izibonelo zekhodi

Ikholi elula kakhulu — dlulisela nje i-imeyili yomsebenzisi:

JavaScript

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

Dlulisela negama lomsebenzisi, ukuze ama-ejenti alibone ku-inbox:

JavaScript

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

Engeza umongo wosizo owusizo ngesikhathi sokuhlonza, uwubuyekeze kamuva, noma ubheke inani elishintshayo ngenkathi ikhasi 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 });

Isibonelo esiphelele nesnippet se-async. Qaphela ukuthi i-identify ingabizwa ngaphambi kwe-init — ubunikazi bufakwa emugqeni bese buthunyelwa lapho nje i-widget ixhuma:

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 lapho umsebenzisi ephuma ukuze usule ubunikazi bakhe futhi uqale iseshini entsha:

JavaScript

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

Kusebenza kanjani

01
I-widget iyalayisha futhi ixhume
I-widget ixhuma ku-Sonny futhi ithumele noma ibuphi ubunikazi obugciniwe lapho ijoyina.
02
Ubunikazi buthunyelwa kuseva
I-Sonny ifuna oxhumana naye onaleyo imeyili endaweni yakho yokusebenza, futhi imdale uma engakabi khona.
03
Izingxoxo ziyaxhunywa
Noma yiziphi izingxoxo ezingaxhunyiwe kuseshini yesivakashi yesiphequluli samanje zixhunywa koxhumana naye ohlonziwe. Ukuhlonza akuhlanganisi umlando phakathi kweziphequluli noma amadivayisi.
04
Isicelo se-imeyili siyeqiwa
Njengoba isivakashi sesivele sihlonziwe, isicelo se-imeyili ngaphakathi kwe-widget siyacindezelwa — akukho ukuphazamiseka kumsebenzisi.

Imithetho yezimfanelo zangokwezifiso

Thumela izimfanelo ezingafika ku-50 ngekholi ngayinye.
Inani lingaba ngumbhalo (string), inombolo, i-boolean, noma i-null. Imibhalo ikhawulelwe ezinhlamvwini ezingu-1000. Dlulisela i-null noma umbhalo ongenalutho ukuze usule inani eligciniwe.
Okhiye kufanele baqale ngohlamvu futhi baqukethe izinhlamvu, izinombolo, nama-underscore kuphela, kuze kube yizinhlamvu ezingu-64.
Laba khiye bagodliwe futhi abanakwa: email, name, id, phone, createdAt, updatedAt.

Ireferensi ye-API

sonny('identify', { email, name?, attributes? }): Ihlonza isivakashi samanje. Isetha i-imeyili negama elingaphoqelekile, yeqa isicelo se-imeyili, futhi ithumele ubunikazi kuseva. Ingabizwa ngaphambi noma ngemuva kwe-init.; emailstringIkheli le-imeyili lesivakashi
namestring?Igama lokubonisa lesivakashi
attributesobject?Izimfanelo zangokwezifiso ezizonamathiselwa koxhumana naye (bona umhlahlandlela wokusetha i-widget ukuze uthole imithetho yokhiye neyamanani)
sonny('identify', { userJwt, name?, attributes? }): Ihlonza ngokuphephile ikhasimende elingenile njengamanje kusuka ku-JWT eyakhiwe yiseva. I-token ihlala enkumbulweni futhi ithunyelwa kuphela kuma-payload ezicelo eziqinisekisiwe noma e-socket.; userJwtstringI-JWT entsha ye-HS256 eyakhiwe yi-backend yakho eqinisekisiwe
namestring?Igama lokubonisa lesivakashi
attributesobject?Izimfanelo zangokwezifiso ezizonamathiselwa koxhumana naye oqinisekisiwe
sonny('setAttributes', { ... }): Ibuyekeza izimfanelo zangokwezifiso zesivakashi esihlonziwe. Kuthunyelwa kuphela amanani ashintshile. Uma isivakashi singakahlonzwa, izibuyekezo ziyalinda bese zithunyelwa ngemuva kokuqhutshwa kwe-identify.; attributesobjectAmapheya okhiye namanani okufanele asethwe. Dlulisela i-null njengenani ukuze usule imfanelo.
sonny('watchAttributes', getter, { interval? }): Ibiza umsebenzi wakho we-getter ngesikhathi esithile futhi ivumelanise ngokuzenzakalelayo noma yiziphi izimfanelo ezishintshile. Kuwusizo lapho amanani afana nohlelo noma ukusetshenziswa eshintsha ngenkathi ikhasi livuliwe.; getterfunctionUmsebenzi obuyisa into yezimfanelo zamanje
intervalnumber?Ukuthi kuhlolwe kangaki, ngama-millisecond. Okuzenzakalelayo ngu-10000, okuncane kakhulu ngu-2000.
sonny('reset'): Isula i-ID ye-widget yesiphequluli samanje, i-imeyili, igama, nomlando wezingxoxo wendawo, bese iqala iseshini entsha yesivakashi. Ayimsusi oxhumana naye noma izimfanelo zakhe ezigciniwe ku-Sonny. Sebenzisa lokhu lapho ephuma.

Udinga usizo?

Bheka umhlahlandlela wokusetha i-widget noma uxhumane nethimba lethu.

Umhlahlandlela wokusetha i-widget Xhumana nathi

Imibhalo ehlobene

Bona ukuthi i-Sonny isiza kanjani

Isofthiwe yengxoxo ebukhoma
Isofthiwe yengxoxo ebukhoma ene-widget yewebhusayithi engenziwa ngokwezifiso, ukuhlonza izivakashi, ukwabela ithimba, umlando wezingxoxo, izinhlelo zeselula, ne-AI ongayikhetha.

Nini ukusebenzisa lokhu

Ubunikazi besivakashi obuqinisekisiwe

Kuvaliwe

Ukuqinisekisa okungaphoqelekile (kunconyiwe)

Dinga ubufakazi ukuze uhlonze

1. Yakha imfihlo yokusayina

2. Yakha i-JWT yesikhashana ku-backend yakho

3. Dlulisela i-JWT kuphela ku-widget

Vuselela, phuma, futhi ushintshanise ngokuphephile

Ukungqubuzana kobunikazi akuhlanganiswa ngokuzenzakalelayo

Ukungena esikhungweni sosizo

Hlola ukungena nokufinyelela

Vuselela futhi uphume

Ukuhlonza nge-imeyili akukhona ukuqinisekisa ubunikazi

Izibonelo zekhodi

Kusebenza kanjani

I-widget iyalayisha futhi ixhume

Ubunikazi buthunyelwa kuseva

Izingxoxo ziyaxhunywa

Isicelo se-imeyili siyeqiwa

Imithetho yezimfanelo zangokwezifiso

Ireferensi ye-API

Udinga usizo?

Imibhalo ehlobene

Bona ukuthi i-Sonny isiza kanjani