Referans

arcy.js'in tek giriş noktası arcy.init(token) çağrısıdır. Her çatıda ve iki kurulum yolunda (npm ve HTML kod parçacığı) aynıdır. Kod yalnızca panele ulaşılmadan önce bilinmesi gerekenleri belirler: yanıt dili, panelin yüklenince açılıp açılmayacağı, içerik yerel ayarı, isteklerin gideceği adres ve bir akışın İstek adımının göndereceği başlıklar. Ajanın personası, kaynakları, akışları, limitleri ve çevirilerinin tamamı panelde yapılandırılır. Token Yapılandır > Kurulum sayfasındadır; kurulumun kendisi Hızlı başlangıç sayfasındadır. ARCY MCP, arcy.js'in parçası değildir; kodlama ajanınızın bağlandığı ayrı bir sunucudur. Ayrıntılar ARCY MCP sayfasındadır.

Hiçbir çağrı hata fırlatmaz, hiçbir promise reddedilmez. Hatalı kullanım, [arcy] ön ekli bir console.warn satırı yazar ve hiçbir şey yapmaz. Uyarıların tamamı Konsol uyarıları bölümündedir.

init(token, options?)

init(token: string, options?: ArcyOptions): Promise<void>

ARCY'yi tek bir ortam için yükler. token, o ortamın herkese açık Token değeridir. Aynı sayfada ikinci bir çağrı ya da token'sız bir çağrı uyarıyla yoksayılır.

options tam olarak altı anahtar kabul eder. Başka bir anahtar, adı yazılan bir uyarıyla yoksayılır.

interface ArcyOptions {
  locale?: string
  defaultOpen?: boolean
  contentLocale?: string
  apiBase?: string
  requestHeaders?: () => Record<string, string> | Promise<Record<string, string>>
  listen?: { posthog?: unknown; mixpanel?: unknown; amplitude?: unknown }
}

import arcy from "arcy.js"

arcy.init("YOUR_ENVIRONMENT_TOKEN", { locale: "tr", contentLocale: "tr-TR" })

arcy.init("YOUR_ENVIRONMENT_TOKEN", {
  requestHeaders: () => ({ Authorization: "Bearer " + getToken() }),
})

import posthog from "posthog-js"
arcy.init("YOUR_ENVIRONMENT_TOKEN", { listen: { posthog } })

identify(userId, attributes?, options?)

identify(userId: string, attributes?: AttributesInput, options?: IdentifyOptions): Promise<void>

Sayfadaki kullanıcının kim olduğunu bildirir. userId boş olmayan bir metin olmalıdır; başka her değer uyarıyla yoksayılır. attributes, yerleşik özniteliklerden ve Yapılandır > Öznitelikler sayfasında tanımladığınız anahtarlardan oluşan düz bir nesnedir. Her değer metin, sayı, mantıksal değer, null, metin dizisi, nesne ya da nesne dizisi olmalıdır. Başka biçimdeki bir değer, örneğin bir Date, anahtarın adını söyleyen bir uyarıyla düşer. Nesne için geçerli üst sınırlar Öznitelikler sayfasındadır.

Üç durum birbirinden ayrıdır: yazmadığınız anahtara dokunulmaz, undefined aynı şeyin JavaScript'teki yazımıdır, null ise saklanan değeri siler. Böylece kimlik sağlayıcınızdan gelen isteğe bağlı bir alanı olduğu gibi geçirebilirsiniz:

arcy.identify(user.id, {
  user_email: user.primaryEmailAddress?.emailAddress,
  user_signed_up_at: user.createdAt.toISOString(),
  plan_value: 249,
  plan_cycle: "monthly",
  plan_currency: "TRY",
})

options.userHash, sunucunuzun hesapladığı kimlik doğrulama imzasını taşır. Tarif Hızlı başlangıç sayfasındadır. Metin olmayan bir userHash uyarıyla yoksayılır.

Yerleşik öznitelikler

ARCY bu anahtarları hiçbir tanım yapmadan her yazılım ürününde tanır. Denetimi geçemeyen bir değer yalnızca o anahtar için reddedilir. Çağrının geri kalanı saklanır ve anahtar Öznitelikler sayfasında reddedilmiş olarak görünür. Yerleşik ya da sizin olsun, kart numarasına, banka hesap numarasına (IBAN) ya da API anahtarına benzeyen her değer de aynı şekilde reddedilir: ARCY ödeme ve kimlik bilgisi verisini hiçbir zaman saklamaz ve reddedilen değeri günlüğe yazmaz.

Dört anahtarı ARCY kendisi doldurur: user_first_seen_at, user_last_seen_at, organization_first_seen_at ve organization_last_seen_at. Bunlardan biri gönderilirse reddedilir.

Kendi öznitelikleriniz user_, organization_ ya da plan_ ile başlayabilir, örneğin user_role. Yalnızca yukarıdaki on beş ad ayrılmıştır. Anahtar kuralları Öznitelikler sayfasındadır.

locale_code bir öznitelik değildir. identify() ya da updateUser() ile gönderildiğinde bu oturumun içerik yerel ayarını belirler; init() çağrısındaki contentLocale ile aynı işi görür. Kullanıcının kaydına hiçbir zaman yazılmaz.

identifyAnonymous(attributes?, options?)

identifyAnonymous(attributes?: AttributesInput, options?: IdentifyAnonymousOptions): Promise<void>

Oturum açmış kullanıcısı olmayan sayfalar için. Alan adınızdaki birinci taraf bir çerezde tutulan kimliği yeniden kullanır ya da yeni üretir. Böylece geri gelen ziyaretçi oturumlar ve alt alan adları boyunca tek kişi sayılır; kayıttan önceki etkinlik kayıttan sonra hesaba bağlanır. Anonim ziyaretçinin sohbet yanıtları, kimliği doğrulanmış kullanıcınınkiyle aynı yapay zeka kredisinden düşer. Sınırlar Limitler sayfasındadır.

options.id ile bu ziyaretçi için kendi kimliğinizi, örneğin bir misafir kimliğini verirsiniz; arcy.js o kimliği kullanır. Bir içe aktarmanın anonymous_id sütununa yazdığınız değeri verin. Ziyaretçi, içe aktardığınız anonim geçmişe bağlanır:

arcy.identifyAnonymous({}, { id: guest.id })

Çağrıyı sayfa yüklenirken, sohbet açılmadan yapın: konuşma sırasında verilen kimlik ziyaretçiyi baştan başlatır. UUID biçimindeki kimlik (sürüm 1 ile 8) küçük harfe çevrilip olduğu gibi kullanılır. Diğer kimliklerin baştaki ve sondaki boşlukları kırpılır, en fazla 256 karakter olabilirler ve sabit bir UUID'ye dönüştürülürler. İçe aktarma da aynı değerden aynı UUID'yi hesaplar. arcy.js'in ürettiği kimlik gibi sizinki de yalnızca ziyaretçinin onayından sonra saklanır. Ret ya da onayın geri çekilmesi kimliği unutturur; bu yüzden kimliği her çağrıda verin. Boş ya da daha uzun bir kimlik uyarıyla yok sayılır ve ziyaretçi arcy.js'in ürettiği kimlikle devam eder.

updateUser(attributes?)

updateUser(attributes?: AttributesInput): Promise<void>

Kimliği değiştirmeden mevcut kimliğe öznitelik ekler. userHash almaz; önceki identify() çağrısının doğrulama durumunu devralır. Herhangi bir identify() ya da identifyAnonymous() çağrısından önce çağrılırsa hiçbir şey göndermez.

reset()

reset(): void

Mevcut kimliği siler ve yeni bir anonim kimlik başlatır. Aynı tarayıcıdaki iki kişi hiçbir zaman birleşmesin diye oturum kapatma işleyicinizden çağırın. Çalışan bir akış varsa onu da bitirir; flow_abandoned işleyiciniz bunu duyar. Ayrılan kişi için bekleyen teklifleri, tetikleyicileri ve Kontrol listesini, onun için saklanan yarım kalmış akışı da siler. Böylece sıradaki kişi temiz bir başlangıç yapar.

consent(granted)

consent(granted: boolean): void

Ziyaretçinin çerez politikanıza verdiği yanıtı kaydeder. init() çağrısından sonra herhangi bir anda, bildiriminizin Kabul işleyicisinden true, Reddet işleyicisinden false ile çağırın. false, ARCY'nin cihaza yazdığı her çerezi ve anahtarı siler. Her yanıtın neyi durdurduğu ve sohbetin nasıl yeniden sorduğu Onay sayfasındadır.

consentState()

consentState(): "granted" | "refused" | null

Ziyaretçinin bu cihazdaki güncel yanıtı. null, henüz yanıt verilmediği anlamına gelir; bildiriminiz bu durumda kendini göstermelidir. HTML snippet yolunda arcy.js yüklenene kadar da null döner; bu yüzden değeri on("ready") içinde okuyun.

onConsent(handler)

onConsent(handler: (granted: boolean) => void): () => void

Sohbet içindeki bir Kabul dahil her kaynaktan gelen her değişiklikte tetiklenir ve bir abonelik iptal işlevi döndürür. Google Consent Mode'u, CMP'nizi ya da kendi bayrağınızı burada güncelleyin. Bağlama örnekleri Onay sayfasındadır.

on(event, handler)

on(event: "ready" | "open" | "close", handler: () => void): () => void
on(
  event: "flow_started" | "flow_completed" | "flow_abandoned",
  handler: (detail: { key: string; source: FlowStartSource }) => void,
): () => void

Bir olaya abone olur ve bir abonelik iptal işlevi döndürür. init() çağrısından önce de çağrılabilir. reset() hiçbir aboneliği silmez.

key, akışın Akışlar sayfasındaki ayarlarında yer alan Anahtar değeridir. source, akışı neyin başlattığını söyler:

Olay adları Akışlar sayfasındaki olaylarla aynıdır. Böylece kendi analitik aracınızdaki sayı ile bir akışın analitiğindeki sayı aynı şeyi sayar:

arcy.on("flow_completed", ({ key, source }) => {
  posthog.capture("flow_completed", { flow: key, source })
})

Bu altı ad dışındaki bir olay adı uyarıyla yoksayılır. Hata fırlatan bir işleyici yakalanır ve uyarı yazılır; diğer işleyiciler ve akış çalışmaya devam eder.

startFlow(key)

startFlow(key: string): void

Bu Anahtar ile yayındaki akışı kendi düğmenizden ya da menünüzden başlatır. Kopyalanacak satır, Akışlar sayfasındaki akış ayarlarında anahtarın yanındadır. Anahtarı değiştirirseniz eski anahtarla yapılan her çağrı çalışmaz.

<button onClick={() => arcy.startFlow("setup_payouts")}>Ödemeleri ayarla</button>

Çağrının arkasında bir tıklama ya da tuşa basma varsa akışı ziyaretçi başlatmış sayılır. Çerez politikanızı henüz kabul etmemiş ya da reddetmiş bir ziyaretçiye önce sohbet açılır ve onay sorulur. Ziyaretçi kabul ettikten sonraki ilk tıklamada akış başlar. Arkasında ikisi de olmayan bir çağrıda, sözgelimi sayfa yüklenirken ya da on("ready") içinde, ilk sözü ARCY almış sayılır. Bu durumda sohbet yalnızca henüz yanıt vermemiş ziyaretçiye onay sorar; reddetmiş ziyaretçi hiçbir şey görmez. Çalışmanın source değeri code olur.

Bu ortamda yayında akışı olmayan bir anahtar ya da kitlesi bu ziyaretçiyi kapsamayan bir akış hiçbir şey başlatmaz ve hiçbir şey göstermez; konsol anahtarın adını yazar. İlk çağrı henüz yüklenirken aynı anahtarla yapılan ikinci çağrı ya da zaten çalışan bir akış için yapılan çağrı yeni bir şey başlatmaz. init() tamamlanmadan yapılan çağrı onu bekler. init() hiç çağrılmadan yapılan çağrı uyarıyla yoksayılır. HTML kod parçacığında bu çağrıyı bir tıklamadan ya da on("ready") içinden yapın. Ayrıntılar Yükleme ve sayfa değişiklikleri bölümündedir.

track(name)

track(name: string): void

Kendi kodunuzdan adlandırılmış bir olay bildirir. Yalnızca ad alır: küçük harf, rakam ve alt çizgi, en fazla 64 karakter, harfle başlar. Bu biçimin dışındaki bir ad düşürülür ve ad başına bir kez konsol uyarısı verilir. Ziyaretçi onay verene kadar hiçbir şey kaydedilmez; init() tamamlanmadan yapılan çağrı onu bekler.

Adı önce tanımlayın. Olaylar sayfasında hiçbir olayın tanımlamadığı bir ad, geldiği anda düşürülür, orada kendi adıyla sayılır ve planınızın izlenen olay hakkından hiç düşmez. Tanımlamak o sayfada tek basıştır.

Tanımlı bir olay; bir akışın Tamamlanma olayı, bir huni adımı, bir Deneyin koşulu, bir Uzmanın neyi saydığı ya da bir Kontrol listesi maddesinin Tamamlanma kuralı olabilir.

Çağrıyı ARCY olmadan da çalışan yola koyun. Sohbetin içinde biten bir akışta aynı olayı İstek adımı sizin yerinize bildirebilir (Akışlar). Bir akışın tamamlanma olayını bugüne kadar yalnızca o adım gönderdiyse ARCY olmadan kimse o ana ulaşamaz. Bu durumda Lift, kendi kodunuz da gönderene kadar o akış için fark göstermez. Olayı sunucudan bildirmenin bir yolu yoktur. track() çağrısını, kendi isteğiniz başarılı olduktan sonra ziyaretçinin tarayıcısından yapın.

arcy.track("checkout_done")

registerHandler(name, handler)

registerHandler(name: string, handler: (inputs: Record<string, string | number | boolean>) => unknown): () => void

Kendi fonksiyonlarınızdan birini, bir akışın İstek adımının yürütebileceği hale getirir. Ürününüzde API rotası olmayan işlemler için kullanın: Next.js Server Action, tRPC yöntemi, GraphQL mutation, CSRF arkasında bir form gönderimi. Endpoint'ler sayfasında o Endpoint'in Nasıl yürütülür değeri Handler olur, Handler adı ise burada verdiğiniz name değeridir.

import { createLead } from "@/app/actions/leads"

arcy.registerHandler("create_lead", ({ email, name }) => createLead({ email, name }))

ARCY fonksiyonunuzu tek bir nesneyle çağırır: Endpoint'in tanımlı girdileri, her biri kendi Türü olarak okunmuş ve Kurallarına göre denetlenmiş halde. Başka hiçbir şey gitmez: akış anahtarı yok, ziyaretçi kimliği yok, öznitelik yok. Sayfanız kimin oturum açtığını zaten bilir, fonksiyonunuz da kendi oturumunu okur. ARCY, döndürdüğünüz değerden Endpoint'in yanıt alanlarını noktalı yollarıyla okur ve döndürdüğünüz hiçbir şeyi ARCY'ye göndermez.

Bir değer ya da bir promise döndürün. Fırlatılan bir hata ve reddedilen bir promise başarısızlıktır; Endpoint'in Başarısızlığı nasıl bildirir işaretinin eşleştiği bir yanıt da başarısızlıktır. Başarısızlık hiçbir çalışma değişkeni yazmaz ve hiçbir olay bildirmez.

Ad küçük harf, rakam ve alt çizgiden oluşur, harfle başlar ve en fazla 64 karakterdir; bu şeklin dışındaki bir ad tek bir konsol uyarısıyla yok sayılır. Aynı adı ikinci kez kaydetmek sessizce en yenisini tutar, böylece geliştirme sırasında yenilenen bir modül sorun olmaz. Dönen değer o kaydı geri alır, yalnızca hâlâ geçerli olan kayıt oysa:

useEffect(() => arcy.registerHandler("create_lead", createLead), [])

init() öncesinde çağırmak güvenlidir; HTML parçacığıyla kurulumda arcy.js yüklenmeden önce de güvenlidir. Kendi betiğinizin başında kaydedin, çağrı arcy.js geldiğinde işler.

Bir akış yürütmeden hiçbir şey olmaz. Kaydettiğiniz fonksiyon yalnızca bir kişinin yayınladığı akışın içinde, o Endpoint'e bağlı bir adımda çalışır; ziyaretçinin girdiği değer de Endpoint'in Kurallarından geçmeden fonksiyonunuza ulaşmaz.

open() ve close()

open(): void
close(): void

Sohbet panelini kendi kodunuzdan açar ya da kapatır. İkisi de eşzamanlıdır. open(), sohbet çubuğu kitlesi dışındaki bir ziyaretçi için de sohbeti açar; panel kapanınca çubuk yeniden çekilir.

VERSION

arcy.VERSION // "0.x.y"

Kurulu arcy.js sürümü, bir destek kaydına yazmak için. arcy.js bu değeri her oturum başında bize de gönderir; ARCY MCP bir güncellemenin yüklendiğini bununla doğrular. Her sürüm Sürüm notları sayfasındadır. 1.0 öncesinde bir sürüm, kodunuzun arcy.js'i nasıl çağırması gerektiğini değiştirebilir. Bu tür her değişiklik "Kodunuzda değişmesi gerekenler" başlığı altında yer alır ve ARCY MCP sayfasındaki arcy.js'i güncelleyin işi bunu sizin yerinize yapar. 1.0 ile birlikte kırıcı bir değişiklik yeni bir ana sürüm ve önceden duyuru demektir.

TypeScript tipleri

arcy.js kendi tiplerini içerir; @types/arcy.js yoktur. Aşağıdakilerin her birini adıyla içe aktarabilirsiniz:

import arcy, { type IdentifyOptions, type FlowEventDetail } from "arcy.js"

Yükleme ve sayfa değişiklikleri

HTML kod parçacığı, arcy.js yüklenene kadar çağrıları sıraya alır. Yüklemeden önce yapılan her çağrı bekletilir ve sırasıyla çalıştırılır; bu yüzden identify() kod parçacığının hemen altında durabilir. init(), identify(), identifyAnonymous() ve updateUser() bir promise döndürür. Bu promise, arcy.js yüklenip çağrıyı çalıştırdığında tamamlanır. on() ve onConsent(), çağrı sıradayken de çalışan bir abonelik iptal işlevi döndürür. consentState() o ana kadar null, VERSION ise undefined döner; ikisini de on("ready") içinde okuyun.

Kod parçacığı, yapıştırıldığı andaki yöntemleri taşır. Kod parçacığınızdan daha yeni bir yöntem arcy.js yüklenmeden çağrılırsa hata fırlatır. startFlow() çağrısını bir tıklamadan ya da on("ready") içinden yapın; bu her kod parçacığında güvenlidir. Dilerseniz kod parçacığını Yapılandır > Kurulum sayfasından yeniden yapıştırın.

Sayfa değişiklikleri için çağrı gerekmez. ARCY, istemci tarafındaki her rota değişikliğini geri ve ileri gezinme dahil kendisi görür. Yol değiştikten yaklaşık yarım saniye sonra yeni sayfada hangi tetikleyicilerin geçerli olduğuna yeniden bakar. Sayfa görüntüleme bildirmek için bir çağrı yoktur.

Yarım kalan bir akış, sayfa tamamen yeniden yüklense de sürer. Bunun için aynı sekmede ve aynı kişiyle, son adımından sonraki 30 dakika içinde kalmak gerekir. Bu süre geçtiyse, başka bir sekmede ya da reset() sonrasında akış kaldığı yerden devam etmez.

arcy.js yalnızca tarayıcıda çalışır. Sunucu tarafında işleme yapan bir çatıda çağrıları bir istemci bileşeninden ya da bileşen yüklendiğinde çalışan bir efektten yapın; sunucu işlemesi sırasında asla çağırmayın.

Her sayfada tek kurulum yolu kullanın. Kod parçacığını ve npm paketini aynı sayfaya asla birlikte yüklemeyin: ikinci kopya uyarıyla yoksayılır.

Konsol uyarıları

Her satır [arcy] ile başlar. Açılı ayraç içindeki kelimeler, <body> dışında, çağrınızdan doldurulur. Uyarı metinleri İngilizcedir; tabloda da olduğu gibi yer alır.

Ayrıca bakın

• Hızlı başlangıç
• Sorun giderme
• ARCY MCP