Kurulum ve hata ayıklama
OneSignal çağrılarınızıOneSignalDeferred.push(async function() { ... }) ile sarma ihtiyacını fark edebilirsiniz
function() içine istediğiniz kadar yöntem ekleyebilirsiniz.
OneSignal SDK, sayfanızda defer özniteliği ile yüklenir. Örneğin:
<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
Bu, OneSignal kodunun HTML belgesi tamamen ayrıştırıldıktan sonra çalışacağı anlamına gelir ve OneSignal SDK’nın siteyi bloke etmesini önler. Ancak bu, OneSignalDeferred değişkeninin var olmasına bağlı olan sayfa betikleri için bir sorun oluşturur. Bunu çözmek için, OneSignal’i sitenize eklediğinizde şununla başlamalıdır:
window.OneSignalDeferred = window.OneSignalDeferred || [];
Bu bir OneSignalDeferred değişkeni oluşturur ve OneSignal zaten yüklenmişse, yüklenen örneğe atanır. Aksi takdirde, OneSignal değişkeni boş bir diziye eşittir - [].
Tüm dizilerin bir .push() fonksiyonu vardır, bu noktada OneSignalDeferred değişkeni basitçe üzerine ittiğimiz fonksiyonların bir dizisidir. SDK sonunda yüklendiğinde, SDK şu ana kadar itilen tüm fonksiyonları işler ve .push()‘u yeniden tanımlar.
init()
OneSignal SDK’yı başlatır. Bu, sitenizin her sayfasında <head> etiketinde bir kez çağrılmalıdır. ONESIGNAL_APP_ID, Anahtarlar ve ID’ler’de bulunabilir.
OneSignal SDK’nın başlatılmasını geciktirmek istiyorsanız, Gizlilik yöntemlerimizi kullanmanızı öneririz.
Init seçenekleri yalnızca Özel Kod Kurulumu ile çalışır. Aksi takdirde, bunlar OneSignal kontrol panelinde yapılandırılır.
| Parametre | Tür | Açıklama |
|---|---|---|
appId | String | Gerekli: Anahtarlar ve ID’ler’de bulunan OneSignal Uygulama ID’niz. |
requiresUserPrivacyConsent | Boolean | Kullanıcı gizlilik onayı sağlayana kadar SDK başlatmayı geciktirir. Kurulumu tamamlamak için setConsentGiven() çağrılmalıdır. |
safari_web_id | String | Yüklenen Safari .p12 sertifikanız için Safari Web ID’si. Web Hızlı Başlangıç. |
promptOptions | Object | İzin istemlerini özelleştirin. Aşağıdaki detaylar. |
notifyButton | Object | Abonelik Zilini etkinleştirin ve yapılandırın. Aşağıdaki detaylar. |
welcomeNotification | Object | Hoş geldin bildirimini özelleştirin veya devre dışı bırakın. Aşağıdaki detaylar. |
persistNotification | Boolean | Chrome (yalnızca masaüstü) - true: bildirim tıklanana kadar kalır, false: kısa süre sonra kaybolur. Firefox/Safari bu ayarı yok sayar. |
webhooks | Object | Olay callback’lerini yapılandırın. Webhook’lara Bakın. |
autoResubscribe | Boolean | Önerilir: Tarayıcı önbelleğini temizleyen veya OneSignal’e geçiş yapan kullanıcıları otomatik olarak yeniden abone eder. Kodda kullanılırsa kontrol paneli ayarını geçersiz kılar. |
notificationClickHandlerMatch | String | "exact" (varsayılan): tam URL eşleşmesi olan sekmeye odaklanır. "origin": aynı alan adına sahip herhangi bir sekmeye odaklanır. |
notificationClickHandlerAction | String | "navigate" (varsayılan): launchURL’ye gider. "focus": mevcut sekmeye odaklanır (yalnızca "origin" eşleşmesi ile kullanılır). |
serviceWorkerParam | Object | Service worker’ın scope’unu ayarlayın. Uygulanabilirse diğer service worker’ın scope’undan farklı olmalıdır. Örnek:{ scope: "/myPath/myCustomScope/" } |
serviceWorkerPath | String | OneSignal service worker dosyasının konumunu ayarlayın. Örnek:"myPath/OneSignalSDKWorker.js" |
promptOptions parametreleri
Kullanıcı izin istemlerini yerelleştirmek veya özelleştirmek için promptOptions kullanın. Tüm alanlar isteğe bağlıdır.
| Parametre | Tür | Açıklama |
|---|---|---|
slidedown | Object | Yapılandırma seçenekleriyle prompts dizisi içerir. |
prompts | Array of Objects | İstem yapılandırmaları dizisi. Örnek:"slidedown": { "prompts": [{...}, {...}] } |
type | String | İstem türleri:
|
autoPrompt | Boolean |
|
delay | Object | Otomatik istemin ne zaman gösterileceğini kontrol eder:{ pageViews: 3, timeDelay: 20 } = 3. sayfa görüntüleme ve 20s bekleme sonrası göster. |
text | Object | Özel metin seçenekleri:
|
categories | Array of Objects | Yalnızca type: category için. Her nesne şunları içerir:tag: dahili anahtarlabel: kullanıcı tarafından görülebilir adÖrnek: [ {tag: "local_news", label: "Local News"} ]. Veri Etiketleri’ne bakın. |
notifyButton parametreleri
Sayfada gösterilen Abonelik Zili’ni (bildirim düğmesi) yapılandırın.
| Parametre | Tür | Açıklama |
|---|---|---|
enable | Boolean | Abonelik Zili’ni etkinleştirir. Varsayılan olarak devre dışı. |
displayPredicate | Function | Zili göstermek/gizlemek için true veya false döndüren özel fonksiyon (veya Promise). Gösterildiğinde bir kez değerlendirilir. |
size | String | 'small', 'medium' veya 'large'. Abonelikten sonra 'small'’a küçülür. |
position | String | 'bottom-left' veya 'bottom-right'. |
offset | Object | CSS piksel ofsetleri: { bottom: '50px', left: '10px' } |
prenotify | Boolean | true ise, “1 okunmamış” ikonu ve özel hover metni gösterir. |
showCredit | Boolean | Popup’ta “Powered by OneSignal“‘i gizlemek için false olarak ayarlayın. |
text | Object | Zil UI’ı için özel metin. |
welcomeNotification parametreleri
İlk kez abonelikten sonra gönderilen hoş geldin bildirimini özelleştirin.
| Parametre | Tür | Açıklama |
|---|---|---|
disable | Boolean | Hoş geldin bildirimini devre dışı bırak. |
message | String | Gerekli: Bildirim mesajı. Boşsa varsayılan olarak 'Thanks for subscribing!' olur. |
title | String | Bildirim başlığı. Varsayılan olarak site başlığı. Kaldırmak için ' ' (boşluk) kullanın (önerilmez). |
url | URL | Kullanıcı bildirime tıkladığında açılacak isteğe bağlı URL. Genellikle gerekli değildir. |
Örnek:
setLogLevel()
Konsola ek loglar yazdırmak için loglama ayarlayın. Daha fazla ayrıntı için Tarayıcı DevTools ile Hata Ayıklama’ya bakın.
JavaScript
'trace''debug''info''warn''error'
Kullanıcı kimliği ve özellikleri
Kullanıcılarınız web sitenizde push bildirimlerine abone olduğunda, OneSignal otomatik olarak bir OneSignal ID (kullanıcı düzeyinde) ve bir Abonelik ID (cihaz düzeyinde) oluşturur. Benzersiz kullanıcı tanımlayıcınızlalogin() çağrısı yaparak birden fazla aboneliği (örneğin, cihazlar, e-postalar, telefon numaraları) tek bir kullanıcıyla ilişkilendirebilirsiniz.
Daha fazla ayrıntı için Kullanıcılar ve Takma Adlar’a bakın.
login(external_id)
Kullanıcı bağlamını sağlanan external_id’ye ayarlar. Bu external_id ile ilişkili tüm Aboneliklerin ve özelliklerin tek bir onesignal_id altında birleştirilmesini sağlar. Daha fazla ayrıntı için Kullanıcılar’a bakın.
Temel davranışlar:
external_idzaten varsa, SDK o kullanıcıya geçer. Giriş öncesi toplanan anonim veriler birleştirilmez ve atılır.external_idyoksa, yerel durum mevcutonesignal_idaltında kaydedilir. Kullanıcı anonimken toplanan tüm veriler saklanır.- SDK, ağ hatası veya sunucu hatası durumunda otomatik olarak yeniden dener.
External ID’nin ayarlandığından ve aboneliğin kullanıcıya bağlandığından emin olmak için bu yöntemi kullanıcı siteyi her açtığında veya Abonelik değişikliği dinleyicisi içinde çağırın.
logout()
Mevcut kullanıcıyı abonelikten ayırır.
- Mevcut push aboneliğinden
external_id’yi kaldırır. - OneSignal ID’yi yeni bir anonim kullanıcıya sıfırlar.
- Yeni veriler (örneğin etiketler, Abonelikler, oturum verileri vb.) artık
loginyöntemiyle tanımlanana kadar yeni anonim kullanıcı üzerinde ayarlanır.
Aboneliği yeni bir anonim kullanıcıya ayarlamak istiyorsanız, kullanıcı uygulamanızdan çıkış yaptığında bunu kullanın.
JavaScript
OneSignal.User.onesignalId
Tarayıcıda yerel olarak kaydedilen mevcut kullanıcının OneSignal ID’sini alın. Kullanıcı durumu başlatılmadan önce çağrılırsa null olabilir. Bunun yerine, kullanıcı durumu değişikliklerini dinlemek için Kullanıcı Durumu addObserver() kullanın.
JavaScript
OneSignal.User.externalId
Tarayıcıda yerel olarak kaydedilen mevcut kullanıcının External ID’sini alın. login yöntemi aracılığıyla ayarlanmamışsa veya kullanıcı durumu başlatılmadan önce çağrılırsa null olabilir. Bunun yerine, kullanıcı durumu değişikliklerini dinlemek için Kullanıcı Durumu addObserver() kullanın.
JavaScript
addEventListener() Kullanıcı Durumu
Kullanıcı bağlamındaki değişiklikleri dinleyin (örneğin, giriş, çıkış, ID atama).
JavaScript
addAlias(), addAliases(), removeAlias(), removeAliases()
Takma adlar alternatif tanımlayıcılardır (kullanıcı adları veya CRM ID’leri gibi).
- Takma ad eklemeden önce
login()ileexternal_idayarlayın.external_idolmadan aboneliklere eklenen takma adlar birden fazla abonelik arasında senkronize olmaz. - Ayrıntılar için Takma Adlar’a bakın.
JavaScript
getLanguage(), setLanguage()
Kullanıcının otomatik algılanan dilini alın ve/veya geçersiz kılın. Mevcut dil kodlarının listesi için Çok dilli mesajlaşma’ya bakın.
JavaScript
Özel olaylar
Özel olay aracılığıyla Yolculukları Tetikleme ve Wait Until adım aktivasyonu.Özel olaylar Web SDK
160500+ gerektirirÖzel olayların izlenmesi için bir kullanıcının giriş yapmış olması gerekir.name- Gerekli. Dize olarak olayın adı.properties- İsteğe bağlı. Olaya eklenecek anahtar-değer çiftleri. Properties sözlüğü veya haritası geçerli bir JSON Nesnesine serileştirilebilir olmalıdır. İç içe değerleri destekler.
os_sdk anahtarı altında uygulamaya özel verileri otomatik olarak properties yüküne ekler. Örneğin, olayları abonelik türüne göre hedeflemek için os_sdk.type’a erişirsiniz.
json
trackEvent()
JavaScript
Veri etiketleri
Etiketler, olaylara veya kullanıcı özelliklerine göre kullanıcılar üzerinde ayarladığınız özelkey : value dize verisi çiftleridir. Daha fazla ayrıntı için Veri Etiketleri’ne bakın.
addTag(), addTags()
Mevcut kullanıcıya tek veya birden fazla etiket ayarlayın.
- Anahtar zaten varsa değerler değiştirilir.
- Planınızın etiket limitini aşmak, işlemlerin sessizce başarısız olmasına neden olur.
JavaScript
removeTag(), removeTags()
Mevcut kullanıcıdan tek veya birden fazla etiketi silin.
JavaScript
getTags()
Kullanıcının etiketlerinin yerel kopyasını döndürür. Etiketler, login() veya yeni uygulama oturumları sırasında sunucudan güncellenir.
JavaScript
Gizlilik
setConsentRequired()
Veri toplama başlamadan önce kullanıcı onayını zorunlu kılar. SDK’yı başlatmadan önce çağrılmalıdır.
Bu yöntem, init yöntemine requiresUserPrivacyConsent: true eklemeyle aynıdır.
JavaScript
setConsentGiven()
Veri toplama için kullanıcı onayını verir veya geri alır. Onay olmadan, OneSignal’e hiçbir veri gönderilmez ve hiçbir abonelik oluşturulmaz.
setConsentRequired()veyarequiresUserPrivacyConsenttrueolarak ayarlanırsa, SDK’mızsetConsentGiventrueile çağrılana kadar tamamen etkinleştirilmez.setConsentGiventrueolarak ayarlanır ve bir Abonelik oluşturulursa, daha sonrafalseolarak ayarlanırsa, o Abonelik artık güncelleme almaz. O Abonelik için mevcut veriler,setConsentGiventekrartrueolarak ayarlanana kadar değişmeden kalır.- Kullanıcı ve/veya Abonelik verilerini silmek istiyorsanız, Kullanıcıyı sil veya Aboneliği sil API’lerimizi kullanın.
JavaScript
Abonelikler
Daha fazla ayrıntı için Abonelikler’e bakın.User.PushSubscription.id
Tarayıcıda yerel olarak kaydedilen mevcut kullanıcının push Abonelik ID’sini alın. Çok erken çağrılırsa null döndürebilir. Değişikliklere tepki vermek için bu veriyi abonelik gözlemleyicisi içinde almanız önerilir.
JavaScript
User.PushSubscription.token
Mevcut push abonelik tokenını döndürür. Çok erken çağrılırsa null döndürebilir. Değişikliklere tepki vermek için bu veriyi abonelik gözlemleyicisi içinde almanız önerilir.
JavaScript
addEventListener() push abonelik değişiklikleri
Bu yöntemi şunlar gibi push abonelik değişikliklerine yanıt vermek için kullanın:
- Cihaz Google (FCM) veya Apple (APNs)‘tan yeni bir push token alır
- OneSignal bir abonelik ID’si atar
optedIndeğeri değişir (örneğinoptIn()veyaoptOut()çağrıldı)- Kullanıcı sistem ayarlarında push iznini değiştirir, ardından uygulamayı açar
onPushSubscriptionChange olayını tetikler. Dinleyiciniz, tam olarak neyin değiştiğini algılayabilmeniz için previous ve current değerlerine sahip bir state nesnesi alır.
Güncellemeleri dinlemeyi durdurmak için ilişkili removeObserver() veya removeEventListener() yöntemini çağırın.
JavaScript
optOut(), optIn(), optedIn
Mevcut push Aboneliğinin abonelik durumunu (subscribed veya unsubscribed) kontrol edin. Sitenizde push abonelik durumunu kontrol etmek için bu yöntemleri kullanın. Yaygın kullanım senaryoları: 1) Çıkış yapan kullanıcılara push gönderilmesini engelleyin. 2) Sitenizde bir bildirim tercih merkezi uygulayın.
optOut(): Mevcut push abonelik durumunu abonelikten çıkarılmış olarak ayarlar (kullanıcının geçerli bir push token’ı olsa bile).optIn(): Üç eylemden birini yapar:- Aboneliğin geçerli bir push token’ı varsa, mevcut push abonelik durumunu
subscribedolarak ayarlar. - Aboneliğin geçerli bir push token’ı yoksa, push izin istemini görüntülemeye çalışır.
- Aboneliğin geçerli bir push token’ı varsa, mevcut push abonelik durumunu
optedIn: Mevcut push abonelik durumu abone isetrue, aksi takdirdefalsedöndürür. Push token geçerliyse ancakoptOut()çağrıldıysa, bufalsedöndürür.
JavaScript
addEmail(), removeEmail()
Mevcut kullanıcıya/kullanıcıdan bir e-posta Aboneliği (e-posta adresi) ekler veya kaldırır. Doğru kullanıcı bağlamını ayarlamak için login()’den sonra addEmail çağırın. Kimlik Doğrulama ile uyumludur.
JavaScript
addSms(), removeSms()
Mevcut kullanıcıya/kullanıcıdan bir SMS Aboneliği (telefon numarası) ekler veya kaldırır. E.164 formatı gerektirir. Doğru kullanıcı bağlamını ayarlamak için login()’den sonra addSms çağırın. Kimlik Doğrulama ile uyumludur.
JavaScript
Slidedown istemleri
Sitelerinizde çeşitli slidedown istemleri görüntüleyin. Daha fazla ayrıntı için Web izin istemleri’ne bakın.- Reddedilirse, gelecekteki çağrılar en az üç gün boyunca yok sayılır. Daha fazla reddetme, kullanıcıya tekrar sorulmadan önce geçmesi gereken süreyi uzatır.
- Geri çekilme davranışını geçersiz kılmak için yönteme
{force: true}geçirin. Ancak, iyi bir kullanıcı deneyimi sağlamak için eylemi düğme tıklaması gibi UI başlatımlı bir olaya bağlayın.
Bu, abonelik için gerekli Yerel Tarayıcı İsteminin yerini almaz. Yerel tarayıcı istemini kullanarak izinleri almanız gerekir.
promptPush()
Push bildirimleri için normal slidedown istemini görüntüler.
- Kategoriler kullanıyorsanız, bunun yerine
promptPushCategories()çağırın. - OneSignal tarafından ayarlanan geri çekilme mantığına tabidir. Daha fazla ayrıntı için Web izin istemleri’ne bakın.
JavaScript
promptPushCategories()
Kategori slidedown istemini görüntüler, kullanıcıların etiketlerini güncellemelerine izin verir. Kullanıcı henüz izin vermediyse yerel bildirim izin istemini de tetikler.
- Kategoriler kullanmıyorsanız, bunun yerine
promptPush()çağırın. - OneSignal tarafından ayarlanan geri çekilme mantığına tabidir. Daha fazla ayrıntı için Web izin istemleri’ne bakın.
JavaScript
promptSms()
SMS abonelik istemini görüntüler.
- OneSignal tarafından ayarlanan geri çekilme mantığına tabidir. Daha fazla ayrıntı için Web izin istemleri’ne bakın.
JavaScript
promptEmail()
E-posta abonelik istemini görüntüler.
- OneSignal tarafından ayarlanan geri çekilme mantığına tabidir. Daha fazla ayrıntı için Web izin istemleri’ne bakın.
JavaScript
promptSmsAndEmail()
SMS ve e-posta abonelik istemlerini aynı anda görüntüler.
- OneSignal tarafından ayarlanan geri çekilme mantığına tabidir. Daha fazla ayrıntı için Web izin istemleri’ne bakın.
JavaScript
addEventListener() Slidedown
Slidedown istem gösterildi olayını algılamak için bir callback ekleyin.
JavaScript
Push bildirimleri
requestPermission()
Yerel tarayıcı istemi aracılığıyla push bildirimleri izni ister. Tarayıcı tarafından ayarlanan geri çekilme mantığına tabidir. Daha fazla ayrıntı için Web izin istemleri’ne bakın.
JavaScript
isPushSupported()
Mevcut tarayıcı web push’u destekliyorsa true döndürür.
JavaScript
OneSignal.Notifications.permission
Sitenin bildirimleri görüntüleme için mevcut iznini gösteren bir boolean döndürür.
true: Kullanıcı bildirimleri görüntüleme iznini vermiştir.false: Kullanıcı bildirimleri görüntüleme iznini reddetmiş veya henüz vermemiştir.
optOut durumunu veya Abonelik ID ve Push Token varlığını hesaba katmaz, bunlar için OneSignal.User.PushSubscription’a bakın.
İzindeki değişiklikleri dinlemek için permissionChange olayını kullanın.
JavaScript
addEventListener() bildirimler
Bir bildirim olayına olay işleyicilerinizi ekleyerek bildirim yaşam döngüsüne bağlanabilirsiniz. addEventListener çağrısı, bildirim olayları için rastgele sayıda olay işleyicisi eklemenizi sağlar.
Olayları dinlemeyi durdurmak için ilişkili removeEventListener() yöntemini çağırın.
JavaScript
permissionChange
Bu olay, kullanıcı İzin Ver veya Engelle’ye tıkladığında veya tarayıcının yerel izin isteğini kapattığında gerçekleşir.
JavaScript
permissionPromptDisplay
Bu olay, tarayıcının yerel izin isteği gösterildiğinde gerçekleşir.
JavaScript
click
Bu olay, bildirimin gövdesi/başlığı veya eylem düğmeleri tıklandığında tetiklenir.
JavaScript
foregroundWillDisplay
Bu olay, bir bildirim görüntülenmeden önce gerçekleşir. Bu olay sayfanızda tetiklenir. Sitenizde birden fazla tarayıcı sekmesi açıksa, bu olay OneSignal’in aktif olduğu tüm sayfalarda tetiklenir.
JavaScript
dismiss
Bu olay şu durumlarda gerçekleşir:
- Bir kullanıcı bildirim gövdesine veya eylem düğmelerine tıklamadan bildirimi kasıtlı olarak kapatır
- Android’de Chrome’da, bir kullanıcı tüm web push bildirimlerini kapatır (bu olay gösterdiğimiz her web push bildirimi için tetiklenir)
- Bir bildirim kendi kendine sona erer ve kaybolur
Bu olay, bir kullanıcı bildirim gövdesine veya eylem düğmelerinden birine tıklarsa gerçekleşmez. Bu bir bildirim
click olayı olarak kabul edilir.JavaScript
setDefaultUrl()
Bildirimler için varsayılan URL’yi ayarlar.
Varsayılan bir URL ayarlamadıysanız, bildiriminiz varsayılan olarak sitenizin kök dizinine açılır.
JavaScript
setDefaultTitle()
Bildirimlerde görüntülenecek varsayılan başlığı ayarlar.
JavaScript
Sonuçlar
sendOutcome()
OneSignal kontrol panelinde görüntülenebilecek bir sonucu tetikler. Bir sonuç adı (string, gerekli) ve bir değer (number, isteğe bağlı) kabul eder. sendOutcome yöntemi aynı sonuç adıyla her çağrıldığında, sonuç sayısı artacak ve sonuç değeri geçilen miktarla artacaktır (dahil edilmişse). Daha fazla ayrıntı için Özel Sonuçlar’a bakın.
JavaScript
sendUniqueOutcome()
OneSignal kontrol panelinde görüntülenebilecek bir sonucu tetikler. Yalnızca sonuç adını (string, gerekli) kabul eder. sendUniqueOutcome, o sonucun sayısını kullanıcı başına yalnızca bir kez artırır. Daha fazla ayrıntı için Özel Sonuçlar’a bakın.
JavaScript