Pushizo Docs
SDK rehberleri

Cordova SDK

cordova-plugin-pushizo — Android ve iOS yerel SDK'larını cordova.exec köprüsüyle saran eklenti; push, in-app, bildirim kutusu, tercihler.

cordova-plugin-pushizo, yerel Pushizo Android (com.pushizo:pushizo-android) ve iOS (Pushizo pod) SDK'larını cordova.exec köprüsüyle sarar. Yüzey OneSignal v5 ve Capacitor eklentisi ile aynıdır; kuyruk, oturum, teslimat geri bildirimi, tetik değerlendirme ve in-app çizimi yerel taraftadır. Örnek: examples/cordova.

  • cordova ≥ 12, cordova-android ≥ 12 (minSdk 24), cordova-ios ≥ 7 (iOS 15+).
  • Eklenti JS'i window.Pushizo ve window.plugins.Pushizo olarak yüklenir; TypeScript tipleri pakettedir (types/index.d.ts).
  • Tüm metotlar Promise döndürür; her add… dinleyici çağrısı aboneliği kaldıran bir fonksiyon döndürür.

Kurulum

cordova plugin add cordova-plugin-pushizo
# monorepo içinden:
cordova plugin add ../../sdk/cordova

Android (FCM)

  1. Firebase konsolunda Android uygulaması ekleyin; google-services.json dosyasını proje köküne koyup config.xml içine ekleyin (köprü Kotlin ile yazıldığından GradlePluginKotlinEnabled zorunludur):
<platform name="android">
    <preference name="GradlePluginKotlinEnabled" value="true" />
    <preference name="GradlePluginGoogleServicesEnabled" value="true" />
    <preference name="GradlePluginGoogleServicesVersion" value="4.4.2" />
    <resource-file src="google-services.json" target="app/google-services.json" />
</platform>
  1. Dashboard → Kanallar → Android Push → Firebase servis hesabı JSON'u (kurulum sihirbazında Cordova seçilebilir).
  2. Eklenti com.pushizo:pushizo-android artefaktına bağlıdır. Maven Central yayınına kadar cd sdk/android && gradle :pushizo:publishToMavenLocal; eklenti mavenLocal() deposunu kendisi ekler.
  3. FCM servisi, POST_NOTIFICATIONS izni ve bildirim Activity'si SDK manifestinden birleşir. Bildirim ikonu: AndroidManifest.xml içinde com.pushizo.sdk.default_notification_icon meta-data'sı.

Eklenti initialize ayarlarını (yalnızca uygulama kimliği ve herkese açık ayarlar) saklar; süreç bildirim tıklaması veya FCM mesajıyla yeniden başladığında SDK WebView yüklenmeden başlatılır (PushizoInitProvider).

iOS (APNs)

  1. config.xml:
<platform name="ios">
    <preference name="deployment-target" value="15.0" />
    <preference name="SwiftVersion" value="5" />
</platform>
  1. Eklenti Push Notifications yetkisini (aps-environment) ve remote-notification arka plan modunu kendisi ekler. Dashboard → Kanallar → iOS Push → .p8 anahtarı veya .p12 sertifikası.
  2. Pushizo pod'u yayınlanana kadar platforms/ios/Podfile içinde pod 'Pushizo', :path => '<repo>/sdk/ios' ve pod install.
  3. APNs token geri çağrıları eklenti yüklenirken AppDelegate'e çalışma zamanında eklenir; AppDelegate'te bu metotlar varsa önce SDK'ya iletilir, sonra sizin kodunuz çalışır. Ek kod gerekmez.
  4. Pushizo SDK'sı UNUserNotificationCenter delegesini üstlenir; başka bir push eklentisiyle (ör. cordova-plugin-firebasex) birlikte kullanmayın.
  5. Zengin medya, rozet ve uygulama kapalıyken received kaydı için Xcode'da (platforms/ios/*.xcworkspace) Notification Service Extension hedefi ekleyin, Podfile'a target 'PushizoNSE' do pod 'Pushizo/Extension' end yazın ve NotificationService sınıfını PushizoNotificationServiceExtension(appId:apiUrl:appGroup:) yardımcısına devredin; uygulama ve NSE'de aynı App Group'u açıp Info.plist'e PushizoAppGroup yazın. cordova platform rm/add ios Xcode projesini yeniden oluşturduğundan NSE hedefi yeniden eklenmelidir. Ayrıntı: iOS SDK.

Başlatma

document.addEventListener('deviceready', async () => {
  // Tıklama dinleyicisini erken ekleyin; uygulama bildirimden açıldıysa tıklama ilk dinleyiciye teslim edilir.
  Pushizo.Notifications.addClickListener((event) => {
    console.log(event.notification.title, event.result.actionId, event.result.url);
  });

  await Pushizo.initialize('app_…', {
    apiUrl: 'https://api.example.com',
    requiresPrivacyConsent: false,
    logLevel: 'warn',               // none | error | warn | info | debug
  });
  await Pushizo.setConsentGiven(true); // requiresPrivacyConsent: true ise; o zamana kadar ağ çağrısı yapılmaz
});

initialize tek nesne de kabul eder: Pushizo.initialize({ appId: 'app_…', apiUrl }).

İzin

const granted = await Pushizo.Notifications.requestPermission(); // Android 13+ POST_NOTIFICATIONS, iOS UNAuthorization
const current = await Pushizo.Notifications.getPermission();
const stop = Pushizo.Notifications.addPermissionObserver(({ permission }) => {}); // removePermissionObserver(cb)

İzin olayları yerel Android/iOS SDK izin gözlemcisinden gelir (izin isteği sonucu ve uygulama ön plana döndüğünde ayarlardan yapılan değişiklik; yalnızca gerçek değişiklikte).

Kullanıcı, abonelik, tag ve alias

await Pushizo.login('user_42', identityHash);   // identity verification açıksa hash zorunlu
await Pushizo.logout();

await Pushizo.User.addTag('plan', 'pro');       await Pushizo.User.addTags({ plan: 'pro', level: 3 }); // sayı/bool metne çevrilir
await Pushizo.User.removeTag('plan');           await Pushizo.User.removeTags(['plan', 'level']);
const tags = await Pushizo.User.getTags();      await Pushizo.User.setLanguage('tr');
await Pushizo.User.addAlias('crm_id', '1001');  // addAliases({ … }), removeAlias('crm_id')
const externalId = await Pushizo.User.getExternalId();
const hsId = await Pushizo.User.getId();
const emails = await Pushizo.User.getEmails();         // bu cihazda addEmail ile kaydedilenler; getSmsNumbers() aynı biçimde

const state = await Pushizo.User.pushSubscription.getState();    // { id, token, optedIn, permission }
await Pushizo.User.pushSubscription.getId();    // getToken(), getOptedIn()
await Pushizo.User.pushSubscription.optIn();    await Pushizo.User.pushSubscription.optOut();
const unsubscribe = Pushizo.User.pushSubscription.addObserver((s) => {}); // removeObserver(cb)

E-posta ve SMS

await Pushizo.User.addEmail('ali@example.com');   // geçersizse INVALID_ARGUMENT
await Pushizo.User.removeEmail('ali@example.com');
await Pushizo.User.addSms('+905551112233');
await Pushizo.User.removeSms('+905551112233');

Kullanıcı tercihleri

const { preferences, categories } = await Pushizo.User.getPreferences();
const updated = await Pushizo.User.setPreferences([   // 1-100 kayıt; güncel liste döner
  { category: 'promo', optedIn: false },                 // channel yok/null = tüm kanallar
  { category: 'news', channel: 'email', optedIn: true }, // ios_push | android_push | web_push | email | sms
]);

Abonelik yoksa NOT_READY; sahiplik kanıtı yerel SDK tarafından eklenir. Tanımsız kategori HS_NOT_FOUND, kategorinin kapsamadığı kanal HS_VALIDATION_ERROR. Kategori nesnesi: key, name/description (dil kodu → metin), channels, defaultOptedIn. Kategori modeli: Tercihler.

Bildirim olayları

Pushizo.Notifications.addForegroundLifecycleListener((event) => {
  event.preventDefault();        // ön planda gösterme; sonra göstermek için: await event.display()
});
Pushizo.Notifications.removeClickListener(cb);   // removeForegroundLifecycleListener(cb)

Olaylar yerel taraftan tek bir keepCallback kanalıyla gelir; kanal açılmadan oluşan olaylar (ör. soğuk başlatma tıklaması) yerel tarafta tamponlanır. Ön plan dinleyicisi varken gösterim JS kararına kadar bekletilir; iOS'ta engellenen bildirim en fazla 25 sn içinde display() ile gösterilebilir. Bildirim nesnesi: title, body, url, imageUrl, deliveryId, messageId, data, androidNotificationId (yalnızca Android).

In-app mesajlar

await Pushizo.InAppMessages.addTrigger('level', 5);   // addTriggers, removeTrigger(s), clearTriggers, getTriggers
await Pushizo.InAppMessages.setScreen('checkout');    // ekrandan çıkarken setScreen(null)
await Pushizo.InAppMessages.setPaused(false);         // await getPaused()
Pushizo.InAppMessages.addClickListener((e) => {});    // { message: { id }, result: { actionId, url } }
Pushizo.InAppMessages.addLifecycleListener({ willDisplay(e) {}, didDisplay(e) {}, willDismiss(e) {}, didDismiss(e) {} });

Mesajlar yerel SDK görünümüyle çizilir (Android Dialog, iOS UIWindow).

Bildirim kutusu

const page = await Pushizo.Inbox.list({ limit: 20 });  // { items, unreadCount, nextCursor, hasMore }
await Pushizo.Inbox.markRead(page.items[0].id);
const unread = await Pushizo.Inbox.markAllRead();
await Pushizo.Inbox.archive(page.items[0].id);
const count = await Pushizo.Inbox.unreadCount();

Kayıtlı abonelik ve kullanıcı gerekir (yoksa NOT_READY). limit 1-200 (varsayılan 50). Zamanlar epoch milisaniyedir.

Olaylar (outcome) ve bildirim tepsisi

await Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9); // ad in-app event tetiklerini de çalıştırır
await Pushizo.Notifications.clearAll();
await Pushizo.Notifications.removeGroupedNotifications('orders');  // Android android_group / iOS thread-id
await Pushizo.Notifications.removeNotification(id);                // Android: notification.androidNotificationId (tamsayı)
await Pushizo.Notifications.removeNotification('istek-kimligi');   // iOS: UNNotificationRequest.identifier
await Pushizo.Debug.setLogLevel('debug');

Hata kodları

Hatalar PushizoError örneğidir ve code alanı taşır:

KodAnlam
INVALID_ARGUMENTGeçersiz e-posta/telefon ya da eksik alan.
NOT_READYinitialize çağrılmadı veya abonelik/kullanıcı henüz kayıtlı değil.
NOT_FOUNDErtelenen ön plan bildirimi bulunamadı ya da zaten gösterildi (event.display()).
NOT_IMPLEMENTEDYerel tarafta tanımsız metot (eklenti JS'i ile yerel kod sürümleri uyuşmuyor).
HS_…Sunucu hata kodu; katalog: Hatalar.

Boş/hatalı argümanlar köprüye gitmeden TypeError / RangeError fırlatır.

Test

cd sdk/cordova && npm install && npm run typecheck && npm test && npm run build

npm run build src/*.ts dosyalarını www/*.js altına derler (eklentiyle yayınlanır, depoda tutulur).

Sorun giderme

BelirtiNeden / çözüm
Android derlemesi Kotlin hatasıyla duruyorconfig.xml içinde GradlePluginKotlinEnabled açık değil.
Android: pushizo-android çözümlenemiyorpublishToMavenLocal çalıştırılmadı.
iOS'ta tıklama/ön plan olayı gelmiyorBaşka bir push eklentisi UNUserNotificationCenter delegesini devralıyor; kaldırın.
NSE hedefi kaybolducordova platform rm/add ios sonrası hedefi ve Podfile girdisini yeniden ekleyin.
requestPermission hep falseAndroid 13+'ta izin reddedildi; iOS'ta Push yeteneği eksik. Diğer belirtiler: Android, iOS.

Capacitor (Ionic) SDK

@pushizo/capacitor — Android ve iOS yerel SDK'larını saran Capacitor 6/7 eklentisi; web'de @pushizo/web'e devreder. Push, in-app, bildirim kutusu, tercihler.

.NET MAUI SDK

Pushizo.Maui — Android ve iOS yerel SDK'larını JSON köprüsüyle saran .NET MAUI paketi (net8.0/net9.0); push, in-app, bildirim kutusu, tercihler.

Bu sayfada

KurulumAndroid (FCM)iOS (APNs)BaşlatmaİzinKullanıcı, abonelik, tag ve aliasE-posta ve SMSKullanıcı tercihleriBildirim olaylarıIn-app mesajlarBildirim kutusuOlaylar (outcome) ve bildirim tepsisiHata kodlarıTestSorun giderme