Sorun giderme

Her Kurulumu doğrula sonucunu, görünmeyen widget'ı, engelleyen Content Security Policy'yi, kaybolan öznitelikleri ve başarısız olan taramayı çözün.

arcy.js Yazılım ürününüze hiçbir zaman hata fırlatmaz. Karşılaştığı her sorun [arcy] ön ekli bir console.warn satırına dönüşür. Önce tarayıcı konsolunu açın; oradaki satır sorunu adıyla söyler. Her uyarının tam metni, nedeni ve çözümü Konsol uyarıları tablosundadır. Aşağıdaki bölümler, çözümü tek satıra sığmayan sorunları anlatır.

Bölümler, birine işaret edebilmeniz için numaralıdır ve numaralar İngilizce sayfayla aynıdır.

Önce şuna bakın:

[arcy] Failed to load. ARCY is disabled.

Betiğin kendisi hiç yüklenmemiştir. Olağan nedenler bir reklam engelleyici, Content Security Policy'niz (2. bölüm) ya da betik yüklenmeden başka sayfaya geçen bir sayfadır.

Bu satır yoksa arcy.js yüklenmiş ancak yerleşmemiştir. İki mesaj nedenini söyler:

[arcy] The page has no <body> to mount into yet. The widget will not render.

init(), body oluşmadan çalışmıştır; çoğunlukla head içinde defer ya da async olmadan duran bir betiktir. Betik etiketini body'nin sonuna taşıyın ya da arcy.init() çağrısını DOM hazır olduktan sonra yapın.

[arcy] This ARCY surface is already on this page. Ignoring the second mount.
[arcy] Another copy of ARCY is already on this page. Ignoring this one.

Kod parçacığı iki kez kuruludur: aynı sayfada hem npm hem HTML yolu vardır ya da HTML kod parçacığı hem bir yerleşime hem bir etiket yöneticisine yapıştırılmıştır. Tek kurulum yolu bırakın, diğerini kaldırın.

2. Content Security Policy'niz widget'ı engelliyor

Widget, politikanız bize ait bir şeyi ilk engellediğinde çözümün tamamını bir kez yazar:

[arcy] This page's Content-Security-Policy is blocking part of the ARCY widget.
Add these to the policy your app sends:
  connect-src https://api.arcyai.com
  font-src    https://api.arcyai.com
  img-src     https://api.arcyai.com blob:
  style-src   'unsafe-inline', or a nonce on the script that loads ARCY

HTML kod parçacığı yolunda listeye script-src https://cdn.arcyai.com de eklenir, çünkü kod parçacığı oraya işaret eden bir betik etiketidir. npm yolunda sohbet paneli, akış motoru ve seçici kendi paketinizin parçasıdır ve hiçbir şey gerektirmez.

Yazmadığınız bir yönerge uygulanmaz; default-src dışında hiçbir şey geri düşmez. Dolayısıyla default-src içermeyen bir politikaya ekleme gerekmez, içeren politikaya yukarıdaki satırlar eklenir. Politikanızın tamamı, tarayıcının ağ sekmesinde belge isteğinin Content-Security-Policy yanıt başlığındadır.

img-src içindeki blob:, ziyaretçinin eklediği görseli göndermeden önce görmesini sağlar.

Nereye yazılır

Politikayı zaten middleware.ts içinde oluşturuyorsanız yönergeleri oraya ekleyin. Aksi hâlde:

// next.config.js
const csp = [
  "connect-src 'self' https://api.arcyai.com",
  "font-src 'self' https://api.arcyai.com",
  "img-src 'self' blob: https://api.arcyai.com",
].join("; ")

module.exports = {
  async headers() {
    return [
      {
        source: "/:path*",
        headers: [{ key: "Content-Security-Policy", value: csp }],
      },
    ]
  },
}

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    "/**": {
      headers: {
        "Content-Security-Policy": [
          "connect-src 'self' https://api.arcyai.com",
          "font-src 'self' https://api.arcyai.com",
          "img-src 'self' blob: https://api.arcyai.com",
        ].join("; "),
      },
    },
  },
})

SvelteKit politikayı kendisi üretir; yönergeleri yapılandırmaya ekleyin:

// svelte.config.js
export default {
  kit: {
    csp: {
      directives: {
        "connect-src": ["self", "https://api.arcyai.com"],
        "font-src": ["self", "https://api.arcyai.com"],
        "img-src": ["self", "blob:", "https://api.arcyai.com"],
      },
    },
  },
}

// src/middleware.ts
export const onRequest = async (context, next) => {
  const response = await next()
  response.headers.set(
    "Content-Security-Policy",
    [
      "connect-src 'self' https://api.arcyai.com",
      "font-src 'self' https://api.arcyai.com",
      "img-src 'self' blob: https://api.arcyai.com",
    ].join("; "),
  )
  return response
}

// app/entry.server.tsx
responseHeaders.set(
  "Content-Security-Policy",
  [
    "connect-src 'self' https://api.arcyai.com",
    "font-src 'self' https://api.arcyai.com",
    "img-src 'self' blob: https://api.arcyai.com",
  ].join("; "),
)

app.use(
  helmet.contentSecurityPolicy({
    directives: {
      connectSrc: ["'self'", "https://api.arcyai.com"],
      fontSrc: ["'self'", "https://api.arcyai.com"],
      imgSrc: ["'self'", "blob:", "https://api.arcyai.com"],
    },
  }),
)

Başlık ayarlayamıyorsanız politikayı head içinde, sayfadaki her betikten önce gelen bir <meta> etiketiyle verin:

html

<meta
  http-equiv="Content-Security-Policy"
  content="connect-src 'self' https://api.arcyai.com; font-src 'self' https://api.arcyai.com; img-src 'self' blob: https://api.arcyai.com"
/>

Panel biçimsiz görünüyor

Widget sayfaya kendi style öğelerini ekler. style-src 'unsafe-inline' varsa yapılacak bir şey yoktur. Nonce kullanıyorsanız da yoktur: widget, kendisini yükleyen betiğin nonce'unu okur ve eklediği her öğeye aynısını damgalar. Panel biçimsizse ve konsol sessizse bakılacak yer burasıdır.

Hiçbir dış origin'e izin vermemek için

Kendi domaininizdeki bir yolu API'mize yönlendirin ve apiBase olarak geçirin. İstekler, yüklemeler ve yazı tipleri artık kendi origin'inizden gelir.

// next.config.js
async rewrites() {
  return [{ source: "/_arcy/:path*", destination: "https://api.arcyai.com/:path*" }]
}

arcy.init("YOUR_ENVIRONMENT_TOKEN", { apiBase: "/_arcy" })

Bu, npm yolundaki her şeyi kapatır. HTML kod parçacığı yolunda script-src içinde https://cdn.arcyai.com hâlâ gerekir.

3. Kurulumu doğrula henüz trafik yok diyor

arcy.init() seçili ortama hiç ulaşmamıştır. Olasılık sırasıyla:

arcy.init() çağrısını yapan sayfa, dağıtımdan bu yana bir tarayıcıda açılmamıştır. Kontrol beklerken sayfayı açıp yenileyin.
init() içindeki token başka bir ortama aittir. Üst satırda doğru ortam seçiliyken Kurulum sayfasından yeniden kopyalayın.
Bir ağ hatası çağrıyı yutuyordur. Tarayıcının ağ sekmesinde init() çağrısının yaptığı isteği bulun.

4. Kurulumu doğrula kod parçacığının başka bir ortamın token'ını taşıdığını söylüyor

Trafik geliyor, ancak başka bir ortamın Kurulum sayfasından kopyalanmış bir kod parçacığından; örneğin Production dağıtımına yapıştırılmış Development kod parçacığından. Ya üst satırda trafik alan ortama geçin ya da canlıdaki kod parçacığının token'ını Kurulum sayfasında gösterilenle değiştirin.

5. Kurulumu doğrula bir sitenin doğrulanmış bir domainin altında olmadığını söylüyor

Token doğrudur, ancak istek çalışma alanınızın doğrulanmış domainlerinden hiçbirinin altında olmayan bir siteden gelmiştir. Sonuç, reddedilen siteyi adıyla gösterir. Site size aitse domainini ya da onun üstündeki bir adı Domainler sayfasında ekleyip doğrulayın. localhost için buna hiçbir zaman gerek yoktur.

6. Kurulumu doğrula kimlik doğrulamanın başarısız olduğunu söylüyor

Oturumlar geliyor, ancak geçirdiğiniz userHash ortamın Secret değeriyle doğrulanmıyor. Kimlik doğrulamayı zorunlu tut açıkken etkilenen her oturum anonim olarak sunulur; o kullanıcılar için öznitelikler ve kişiselleştirme durur.

İmzalama kodunuzu tarifle karşılaştırın: identify() çağrısına geçirdiğiniz metnin aynısının, Secret ile anahtarlanmış, onaltılık kodlanmış HMAC-SHA256 özeti. En sık neden tür uyuşmazlığıdır: sunucuda tam sayı, tarayıcıda metin olan kimlikler. 42 üzerinden alınan bir imza "42" kimliğini doğrulamaz. Secret'ı yenilediyseniz yenisini dağıtın; yenilemenin ne yaptığı API anahtarları sayfasındadır.

7. Özel bir öznitelik hiçbir yerde görünmüyor

Kurulumu doğrula, bilinmeyen öznitelikleri adıyla listeler: tanımsız gelen bir anahtar düşer, hiçbir zaman saklanmaz. Anahtarı Öznitelikler sayfasında tanımlayın ve yeniden gönderin. Tanımsız gelen trafik geriye dönük doldurulmaz.

Konsolda bunun yerine şunu görüyorsanız sorun değerin biçimindedir:

[arcy] identify() dropped "some_key": an attribute must be a string, number,
boolean, null, or an array of strings.

İç içe bir nesneyi, bir işlevi ya da bir Date değerini geçirmeden önce bu biçimlerden birine indirgeyin.

8. identify() veya updateUser() hiçbir şey yapmıyor gibi

[arcy] identify() needs a user id. Ignoring the call.
[arcy] identify() was called before init(). Ignoring.

İlki, kullanıcı kimliğinin boş, undefined ya da metin dışı olduğunu söyler. İkincisi, kimlik durumunuzla betik etiketi arasındaki bir yarıştır: identify() çağrısını oturumunuzun hazır olduğu yerden, init() sayfada bir kez çalıştıktan sonra yapın.

Herhangi bir identify() ya da identifyAnonymous() çağrısından önce çalışan updateUser() hiçbir şey göndermez, çünkü güncellenecek bir profil henüz yoktur.

9. @types/arcy.js 404 dönüyor

npm error 404 Not Found - GET https://registry.npmjs.org/@types%2farcy.js

Öyle bir paket yoktur. arcy.js kendi TypeScript tiplerini paketle gönderir; o satırı silin ve yalnızca arcy.js kurun. Editörünüz tiplerin eksik olduğunu söylemeye devam ederse npm install arcy.js@latest çalıştırın.

10. Uzun süre açık kalan sekmede sohbet paneli açılmıyor

ARCY sohbet panelini, akış motorunu ve seçiciyi adında sürüm damgası taşıyan ayrı dosyalar olarak gönderir. Bir yayından önce açılmış sayfa eski adları tutar; ilk tıklama artık var olmayan bir dosyayı ister. arcy.js bu durumda CDN'e güncel adları sorar ve onları yükler. Ziyaretçi panelin açıldığını görür, konsola bir şey yazılmaz.

Yalnızca panel yine açılmıyorsa ve şunu görüyorsanız bir şey yapın:

[arcy] Failed to load https://cdn.arcyai.com/arcy.chat.<version>.js. The chat panel will not
open. If this page sets a Content-Security-Policy, it must allow scripts from
https://cdn.arcyai.com.

O zaman ikinci deneme de başarısız olmuştur. Neden politikanız (2. bölüm), ziyaretçinin makinesindeki bir reklam engelleyici ya da kurumsal vekil sunucu, ya da ağınızdaki bir filtreleme geçididir. Sayfayı yenilemek her zaman çalışır. Bunun için Yazılım ürününüze bir yenileme uyarısı eklemeyin.

11. Web tarayıcı kaynağı Başarısız görünüyor

Bildirim eğitimin başarısız olduğunu söyler ve satırda Başarısız yazar. Nedeni görmek için Başarısız üzerine gelin ya da Tab tuşuyla ona ulaşın; bildirim de aynı cümleyi gösterir. Neden bulunamayan bir adres, bir ret, bir sunucu hatası ya da zaman aşımıysa siteyi veya Başlangıç URL'si alanını düzeltin, sonra yeniden Eğit düğmesine basın. Sayfaların hazırlanamadığı yazıyorsa yeniden Eğit düğmesine basın. Aynı sonuç tekrarlanırsa bize ulaşın.

En sık nedenler sitenizin kendi robots.txt dosyasından gelir. Satırdaki Günlüğü görüntüle seçeneğinde, ARCY'nin uzak tutulduğu her sayfanın yanında Skipped: yazar. Dosyayı terminalinizden okuyun:

curl https://siteniz.com/robots.txt

Neden, sitenin "robots.txt dosyasında botları engellediğini" söylüyorsa. Tüm botlar için yazılmış kurallar geçerlidir. Ya kaynakta robots.txt kurallarına uy açıktır ya da site doğrulanmış bir domainin altında değildir ve iş e-postanızın domaini de değildir (ARCYBot). Bu durumdaki dosya genellikle her tarayıcıyı her sayfadan uzak tutar:

User-agent: *
Disallow: /

Bu, test ya da ön izleme derlemelerinin yayınladığı dosyadır. Next.js projelerinde en sık neden, "indexable" türünde bir ortam değişkeninin canlı ortamda boş bırakılmasıdır; app/robots.ts o zaman her şeyi engelleyen dala düşer. Aynı dosya arama motorlarını da sitenizden uzak tutar.

Site doğrulanmış bir domainin altındaysa kaynakta robots.txt kurallarına uy seçeneğini kapatın ve Eğit düğmesine basın; yayınlamanız gereken bir şey yoktur. Değilse dosyayı düzeltin. Canlı ortamda taramaya izin vermesini sağlayın ya da arama motorlarını engelli bırakan bir ARCY grubu ekleyin:

User-agent: ARCYBot
Allow: /

Neden, sitenin robots.txt dosyasında "ARCYBot için yazılmış bir kural" olduğunu söylüyorsa. ARCYBot'u adıyla anan bir gruba, robots.txt kurallarına uy ne gösterirse göstersin her zaman uyulur. Bu grubu Allow: / olarak değiştirin ya da silin.

Dosyayı hangi yolla değiştirirseniz değiştirin, yayınlayın ve engel kalkana kadar curl komutunu yineleyin. Sonra Eğit düğmesine basın.

www.siteniz.com ile siteniz.com için ayrı bir işlem gerekmez. Biri diğerine yönlendirir; tarayıcı yönlendirmeyi izler ve aynı robots.txt dosyasına ulaşır.