HitKey сәйкестік

HitKey пайдаланушыларды қалай анықтайтынын түсіну дұрыс интеграция үшін маңызды.

Негізгі қағида

HitKey = адам, email емес.

Адамның көптеген электрондық пошта мекенжайлары болуы мүмкін. Email-дер өзгереді — адамдар провайдерлерді ауыстырады, компаниялар домендерді өзгертеді, пайдаланушылар жеке және жұмыс email-дерін қосады. Бірақ адам сол күйінде қалады.

sub — Тұрақты идентификатор

/oauth/userinfo шақырғанда жауапта sub claim бар:

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com"
}

sub өрісі:

• UUID — әмбебап бірегей, ешқашан қайта пайдаланылмайды
• Өзгермейтін — берілген пайдаланушы үшін ешқашан өзгермейді
• Сыртқы кілт ретінде сақтауыңыз керек жалғыз идентификатор

Email-ді ешқашан негізгі кілт ретінде пайдаланбаңыз

HitKey-дегі email-дер:

• Өзгермелі — пайдаланушылар кез келген уақытта әдепкі email-ді өзгерте алады
• Көптік — бір пайдаланушыда 5, 10 немесе одан да көп верификацияланған email болуы мүмкін
• Кэштелген — userinfo-дағы email өрісі ағымдағы әдепкіні көрсетеді, ол өзгеруі мүмкін

Егер email-ді пайдаланушы идентификаторы ретінде пайдалансаңыз, пайдаланушы email-ін өзгерткенде қайталанатын аккаунттар жасайсыз.

Дұрыс интеграция үлгісі

Деректер қорыңыздың схемасы

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  hitkey_user_id UUID NOT NULL UNIQUE, -- /oauth/userinfo-дан алынған sub
  email TEXT,                           -- кэштелген, әр кіруде жаңартылады
  display_name TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Әр OAuth кіруде

const userinfo = await fetch('https://api.hitkey.io/oauth/userinfo', {
  headers: { Authorization: `Bearer ${accessToken}` }
}).then(r => r.json())

// sub бойынша табу немесе жасау — ЕШҚАШАН email бойынша емес
let user = await db.users.findBy('hitkey_user_id', userinfo.sub)

if (!user) {
  user = await db.users.create({
    hitkey_user_id: userinfo.sub,
    email: userinfo.email,
    display_name: userinfo.display_name
  })
} else {
  // Әр кіруде кэштелген өрістерді жаңарту
  await user.update({
    email: userinfo.email,
    display_name: userinfo.display_name
  })
}

Жиі кеткен қате

// ҚАТЕ — email өзгерген кезде қайталанатын аккаунттар жасайды
let user = await db.users.findBy('email', userinfo.email)

Көп email қолдау

HitKey пайдаланушыларында бірнеше верификацияланған электрондық пошта мекенжайлары болуы мүмкін:

• Әдепкі email — userinfo.email-де қайтарылады
• Қосымша email-дер — HitKey бақылау тақтасы арқылы басқарылады
• Верификация — әр email тәуелсіз верификацияланады

Пайдаланушы әдепкі email-ін өзгерткенде, келесі /oauth/userinfo шақыруы жаңасын қайтарады. Сіздің қосымшаңыз кэштелген көшірмесін жаңартуы тиіс.

Ат құрылымы

HitKey халықаралық ат форматтарын қолдайды:

Өріс	Сипаттама	Мысал
name	Толық пішімделген ат	"John Doe"
given_name	Жеке/аты	"John"
family_name	Тегі	"Doe"
display_name	Пайдаланушының қалаған көрсетілетін аты	"John"

Аттар пайдаланушының preferred_order параметрі арқылы батыс ("John Doe") және шығыс ("Doe John") конвенцияларына сәйкес құрылымдалуы мүмкін.

Қорытынды

Дұрыс	Бұрыс
sub-ды сыртқы кілт ретінде пайдалану	email-ді бірегей кілт ретінде пайдалану
hitkey_user_id-ге UNIQUE шектеу қою	Email тұрақты деп есептеу
Әр кіруде кэштелген email-ді жаңарту	userinfo шақыруын өткізіп жіберу
Қосымша өрістердің болмауын өңдеу	Барлық ат өрістерін талап ету