Hızlı başlangıç

ARCY, ürününüze arcy.js eklenerek kurulur. İki yol ve üç zorunlu adım vardır ve tamamı, bir geliştiricinin bu sayfanın dışında hiçbir şey okumadan bitirebileceği şekilde tasarlanmıştır.

Ortamınıza ait kurulum kod parçacıklarını, gerçek token'ı yerleştirilmiş halde, panelde Settings > Installation altında bulabilirsiniz. Bu sayfa da aynı adımları baştan sona anlatır.

Zorunlu adımlar

Kurulum yönteminizi seçin

• NPM, modül paketleyici kullanan tarayıcı uygulamaları için (Webpack, Vite, Rollup). Önerilen yol.
• HTML, etiket yöneticileri dahil geri kalan her şey için. Kapanış </body> etiketinden önce yapıştırılan tek bir kod parçacığı.

Birini seçin. Aynı sayfaya asla ikisini birden kurmayın.

Kurun

NPMHTML

Önce terminalinizde şunu çalıştırın:

npm install arcy.js

Sonra uygulamanız ilk açıldığı yerde arcy nesnesini içe aktarıp kullanın:

import arcy from "arcy.js"

arcy.init("YOUR_ENVIRONMENT_TOKEN") // Gerçek token'ı Settings > Installation ekranından kopyalayın
arcy.identify("USER_ID", {
  user_first_name: "USER_FIRST_NAME",
  user_last_name: "USER_LAST_NAME",
  user_email: "USER_EMAIL",
  user_signed_up_at: "USER_SIGNED_UP_AT",
})

Bunu yalnızca NPM kullanmıyorsanız yapın. Panelinizdeki Settings > Installation ekranından kod parçacığını kopyalayın ve HTML belgenizde kapanış </body> etiketinden önce yapıştırın.

Kod parçacığının iki bölümü vardır:

1. ARCY'nin yükleyici betiği. Küçültülmüş, kendi kendine yeten ve ortamınızın token'ını zaten taşıyan bir betiktir. arcy.js'i eşzamansız yükler, dolayısıyla sayfa yükleme hızınız etkilenmez ve betik yüklenmeden önce yapılan çağrıları sıraya alır. Olduğu gibi yapıştırın. Onu okumanız, düzenlemeniz, sürümlemeniz veya barındırmanız hiçbir zaman gerekmez.
2. Sizin identify betiğiniz. arcy.identify() çağrısını içeren kısa ve okunabilir bir betik. Düzenlediğiniz tek bölüm budur.

<script>
  arcy.identify("USER_ID", {
    user_first_name: "USER_FIRST_NAME",
    user_last_name: "USER_LAST_NAME",
    user_email: "USER_EMAIL",
    user_signed_up_at: "USER_SIGNED_UP_AT",
  })
</script>

init() içindeki token tek bir ortamı tanımlar (Production, Staging vb.). Tasarım gereği açıktır ve sayfa kaynağınızda görünür, dolayısıyla yayınlanması güvenlidir. Her ortamın kendi token'ı vardır; başka bir ortamın kod parçacığını almak için panel kenar çubuğundaki ortam değiştiriciyi kullanın.

Yer tutucuları değiştirin

Yer tutucuları kimlik veya oturum katmanınızdan gelen gerçek, dinamik değerlerle değiştirin:

Yer tutucu	Anlamı
USER_ID	Oturum açmış kullanıcının kendi veritabanınızdaki kimliği
USER_FIRST_NAME	Kullanıcının adı, dinamik bir değer olarak
USER_LAST_NAME	Kullanıcının soyadı, dinamik bir değer olarak
USER_EMAIL	Kullanıcının gerçek e-postası, dinamik bir değer olarak
USER_SIGNED_UP_AT	Kullanıcının kayıt zamanı. ISO 8601, örn. 2019-12-11T12:34:56Z

Bitirdiğinizde panelin Installation sayfasındaki Verify installation düğmesine tıklayın. Bu düğme trafiğin ortamınızdan geldiğini doğrular ve sık karşılaşılan hataları tek tek teşhis eder: henüz trafik yok, doğrulanmamış Origin ya da başka bir ortamın token'ını taşıyan kod parçacığı.

İsteğe bağlı adımlar

Özel özellikler ekleme

identify() içindeki özellikler nesnesi teknik olarak isteğe bağlıdır, ama gönderdiğiniz özellikler, ARCY'nin size ne kadarını söyleyebileceğini belirler. Hiçbir şey göndermezseniz widget yine çalışır, panel ise neredeyse işe yaramaz.

• Gelirdeki riski gösteren içgörüleri açmak için plan_value ve plan_cycle gönderin. Bunlar olmadan ARCY'nin zorlanan bir hesaba iliştirebileceği bir gelir rakamı olmaz; içgörü zayıflamaz, tamamen imkansız hale gelir.
• Tek tek kullanıcılar yerine hesap düzeyinde toplamlar için organization_id gönderin.
• Ürününüzün kullanıcı hakkında bildiği diğer her özel özelliği de ekleyin.

Özel özellikleri ARCY saklamadan önce tanımlamanız gerekir: her birini panelde Agent > Attributes altında tanımlayın, sonra göndermeye başlayın. Tanımı olmayan bir anahtar kaydedilmez; sayılır ve Verify installation ekranında adıyla listelenir, yani sessizce yok sayılmaz. Böylece bir yazım hatası şemanıza kalıcı olarak yerleşmez.

Kimlik doğrulamayı zorunlu kılma

Canlı ortam için kesinlikle önerilir. Bu olmadan herkes sitenizi açıp tarayıcı konsoluna arcy.identify("baskasinin-kimligi") yazabilir ve o kişinin konuşma geçmişini widget üzerinden okuyabilir. Kimlik doğrulama, her kullanıcı kimliğini tarayıcının hiç görmediği bir Secret ile kendi sunucunuzda imzalatarak bunu kapatır.

Arka ucunuzda bir satır ve ön yüzde bir ek argüman gerektirir.

1. Secret değerinizi alın

Ortamınızın Secret değeri panelde Agent > Environments altındadır. Ortam oluşturulurken bir kez ve her döndürdüğünüzde bir kez daha gösterilir, dolayısıyla diğer sunucu tarafı kimlik bilgilerinizi nerede tutuyorsanız orada saklayın.

2. Kullanıcı kimliğini sunucunuzda imzalayın

İmza, kullanıcı kimliğinin Secret ile üretilmiş HMAC-SHA256 özetidir ve onaltılık olarak kodlanır. Yalnızca kullanıcı kimliğini kapsar, özellikleri değil. Intercom ile Segment'in kullandığı tarifin aynısı olduğu için mevcut bir uygulamayı çoğu zaman olduğu gibi taşıyabilirsiniz.

Sayfayı oluşturduğunuz ya da oturumu döndürdüğünüz yerde hesaplayın ve sonucu kullanıcı kimliğiyle birlikte ön yüze geçirin.

import { createHmac } from "node:crypto"

const userHash = createHmac("sha256", process.env.ARCY_SECRET)
  .update(String(user.id))
  .digest("hex")

import hashlib, hmac, os

user_hash = hmac.new(
    os.environ["ARCY_SECRET"].encode("utf-8"),
    str(user.id).encode("utf-8"),
    hashlib.sha256,
).hexdigest()

user_hash = OpenSSL::HMAC.hexdigest("SHA256", ENV["ARCY_SECRET"], user.id.to_s)

$userHash = hash_hmac('sha256', (string) $user->id, getenv('ARCY_SECRET'));

3. Değeri identify() işlevine geçirin

Hash'i üçüncü argümanda, bir seçenekler nesnesinin içinde gönderirsiniz:

arcy.identify("USER_ID", {
  user_first_name: "USER_FIRST_NAME",
  user_email: "USER_EMAIL",
}, {
  userHash: "USER_HASH", // sunucunuzda hesaplanır, tarayıcıda asla
})

identifyAnonymous() ve updateUser() hash almaz. İlki bir kullanıcı kimliği iddia etmez, ikincisi ise kendisinden önce gelen identify() çağrısının doğrulama durumunu devralır.

4. Zorunlu kılmayı açın

Siz açana kadar doğrulama deneme modunda çalışır: imzalar kontrol edilir ve sonuç kaydedilir, ama kimse geri çevrilmez. Bu bilerek böyle. İmzalamanız kimseyi kapıda bırakabilecek hale gelmeden önce doğru çalıştığını görebilirsiniz.

Sonuçları bir süre izleyin, temiz olduklarında ortam için Enforce identity verification ayarını açın. Bundan sonra imzası doğrulanmayan bir çağrı güvenilir sayılmaz: oturum, kanıtlayamadığı bir kullanıcıya bağlanmak yerine anonim olarak devam eder.

Secret değerini döndürme

Döndürme sayfanızı değil arka ucunuzu etkiler; bu yüzden ARCY, döndürmenin ardından 24 saat boyunca önceki Secret ile üretilmiş imzaları da kabul eder. Bu süre, yeni Secret'ı yayına alacak vakti bulmanız ve arada kullanıcılarınızın anonime düşmemesi içindir.

Secret sızdığı için döndürdüyseniz bu süreyi beklemeyin: aynı ekrandan önceki Secret'ı hemen iptal edin. Bu anında geçerli olur ve eski değerle üretilen her imza doğrulanmayı bırakır.

Oturum açmamış kullanıcılar için kurulum

Oturum açmış kullanıcısı olmayan herkese açık sayfalarda identify() yerine şunu kullanın:

arcy.identifyAnonymous()

Benzersiz bir kimlik üretilip localStorage içinde saklanır, sonraki ziyaretlerde yeniden kullanılır, böylece geri dönen anonim bir ziyaretçi oturumlar arasında aynı kullanıcıdır.

Etiket yöneticisiyle kurulum

HTML yolu, Google Tag Manager gibi bir etiket yöneticisinin içinde de aynen çalışır:

1. Yeni bir Custom HTML etiketi oluşturun.
2. Settings > Installation ekranındaki HTML kod parçacığının tamamını, her iki betik dahil, yapıştırın.
3. Tetikleyiciyi All Pages olarak ayarlayın ve kapsayıcıyı yayınlayın.

Yükleyici çift başlatmaya karşı korumalıdır; yani etiket yöneticilerinde sık görüldüğü gibi kod parçacığı iki kez çalışsa bile hiçbir şey bozulmaz. <script> etiketlerini temizleyen etiket yöneticisi korumalı alanlarında ise kod parçacığının çalışabilmesi için özel HTML'e izin verilmesi gerekir.