Pushizo Docs
SDK rehberleri

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.

@pushizo/capacitor, yerel Pushizo Android (com.pushizo:pushizo-android) ve iOS (Pushizo pod / SPM) SDK'larını sarar; web platformunda Web SDK'ya (@pushizo/web) devreder. Kuyruk, oturum, teslimat geri bildirimi, tetik değerlendirme ve in-app çizimi yerel taraftadır. Yüzey OneSignal v5 ile ve Cordova eklentisi ile aynıdır. Örnek: examples/ionic-capacitor.

  • Capacitor 6 ve 7, Android minSdk 23, iOS 15+.
  • Tüm metotlar Promise döndürür; olay dinleyicisi ekleyen her add… çağrısı aboneliği kaldıran bir fonksiyon döndürür.

Kurulum

npm install @pushizo/capacitor @pushizo/web
npx cap sync

@pushizo/web yalnızca uygulama web'de de çalışacaksa gereklidir; native derlemelerde dinamik içe aktarıldığı için yüklenmez.

Android (FCM)

  1. Firebase konsolunda Android uygulaması ekleyin, google-services.json dosyasını android/app/ altına koyun. Capacitor şablonu com.google.gms.google-services eklentisini dosya varsa otomatik uygular.
  2. Dashboard → Kanallar → Android Push → Firebase servis hesabı JSON'u (kurulum sihirbazında Capacitor/Ionic seçilebilir).
  3. Eklenti com.pushizo:pushizo-android artefaktına bağlıdır; sürüm variables.gradle içinde pushizoAndroidVersion ile değiştirilebilir. Maven Central yayınından önce monorepo içinden: cd sdk/android && gradle :pushizo:publishToMavenLocal ve android/build.gradle → allprojects.repositories içine mavenLocal().
  4. POST_NOTIFICATIONS, FCM servisi ve bildirim açma Activity'si SDK manifestinden birleşir. Bildirim ikonu: AndroidManifest.xml içinde com.pushizo.sdk.default_notification_icon meta-data'sı.

Eklenti, JS ile yapılan ilk 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, böylece tıklama ve received kaydı kaybolmaz.

iOS (APNs)

  1. Xcode → Signing & Capabilities: Push Notifications, Background Modes → Remote notifications.
  2. Dashboard → Kanallar → iOS Push → .p8 anahtarı (Key ID, Team ID, bundle id) veya .p12 sertifikası.
  3. APNs token'ını eklentiye iletin (ios/App/App/AppDelegate.swift):
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
    NotificationCenter.default.post(name: .capacitorDidFailToRegisterForRemoteNotifications, object: error)
}
  1. CocoaPods: npx cap sync ios eklentinin PushizoCapacitor pod'unu kurar; bu pod CocoaPods trunk'taki Pushizo pod'una (~> 0.1) bağımlıdır, ios/App/Podfile içine ayrıca satır eklemeniz gerekmez. SPM (Capacitor 7): paket https://github.com/exec0de/pushizo-ios.git deposundan çözülür.
  2. Zengin medya, rozet ve uygulama kapalıyken received kaydı için Notification Service Extension hedefi (iOS 15) 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 uygulamanın Info.plist'ine PushizoAppGroup olarak yazın (verilmezse group.<bundle id>.pushizo). Ayrıntı: iOS SDK.

Pushizo SDK'sı UNUserNotificationCenter delegesini üstlenir; aynı uygulamada @capacitor/push-notifications kullanmayın.

Web

PushizoSDKWorker.js dosyasını sitenizin köküne koyun; gerekirse initialize(appId, { web: { serviceWorkerPath: '/PushizoSDKWorker.js', serviceWorkerScope, allowLocalhostAsSecureOrigin } }). Web'de removeNotification, User.getEmails ve User.getSmsNumbers yoktur (UNAVAILABLE), clearAll service worker bildirimlerini kapatır, engellenen ön plan bildirimi sonradan gösterilemez.

Başlatma

import { Pushizo } from '@pushizo/capacitor';

// Tıklama dinleyicisini mümkün olduğunca erken ekleyin: bildirimden açılışta bekleyen 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 }) => {});
stop(); // ya da removePermissionObserver(cb)

İzin olayı yerel SDK izin gözlemcisinden gelir: izin isteği sonuçlandığında ve uygulama ön plana döndüğünde (ayarlardan değiştiyse) yalnızca gerçek değişiklikte iletilir.

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, vip: true }); // sayı/bool metne çevrilir, null/undefined atlanır
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) => console.log(s.id, s.optedIn)); // 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();
for (const c of categories) console.log(c.key, c.name.tr ?? c.name.en, c.channels, c.defaultOptedIn);
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
]);

Tercihler bir abonelik ister (yoksa NOT_READY); sahiplik kanıtı yerel SDK tarafından eklenir. Tanımsız kategori HS_NOT_FOUND, kategorinin kapsamadığı kanal HS_VALIDATION_ERROR ile reddedilir. updatedAt epoch milisaniyedir. Web'de setPreferences güncel listeyi okuyup kategori/kanalı denetler, yazmayı web SDK'nın çevrimdışı kuyruğuna verir. Kategori modeli: Tercihler.

Bildirim olayları

Pushizo.Notifications.addForegroundLifecycleListener((event) => {
  if (event.notification.data.silent_in_app === '1') {
    event.preventDefault();          // gösterme; sonra göstermek için: await event.display()
  }
});
Pushizo.Notifications.removeClickListener(cb);   // removeForegroundLifecycleListener(cb)

Ön plan dinleyicisi eklendiğinde yerel SDK gösterimi JS kararına kadar bekletir; hiçbir dinleyici preventDefault() çağırmazsa bildirim hemen gösterilir. 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.addTriggers({ level: 5, vip: true }); // addTrigger, removeTrigger(s), clearTriggers, getTriggers
await Pushizo.InAppMessages.setScreen('checkout');               // ekrandan çıkarken setScreen(null)
await Pushizo.InAppMessages.setPaused(true);                     // await getPaused()
Pushizo.InAppMessages.addClickListener((e) => console.log(e.message.id, e.result.actionId, e.result.url));
Pushizo.InAppMessages.addLifecycleListener({ willDisplay: (e) => {}, didDisplay: (e) => {}, willDismiss: (e) => {}, didDismiss: (e) => {} });

Mesajlar yerel SDK'nın kendi 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);         // güncel öğeyi döndürür
const unread = await Pushizo.Inbox.markAllRead();       // kalan okunmamış sayısı
await Pushizo.Inbox.archive(page.items[0].id);
const count = await Pushizo.Inbox.unreadCount();
const next = page.hasMore ? await Pushizo.Inbox.list({ cursor: page.nextCursor! }) : null;

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();                           // tepsi/bildirim merkezi + rozet
await Pushizo.Notifications.removeGroupedNotifications('orders');  // Android android_group / iOS thread-id
await Pushizo.Notifications.removeNotification(n.androidNotificationId!); // Android tepsi kimliği
await Pushizo.Notifications.removeNotification('istek-kimligi');          // iOS: UNNotificationRequest.identifier
await Pushizo.Debug.setLogLevel('debug');

Hata kodları

Reddedilen Promise'in code alanı:

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()).
UNAVAILABLEWeb'de desteklenmeyen işlem (removeNotification, getEmails/getSmsNumbers, engellenmiş bildirimi sonradan display()).
HS_…Sunucu hata kodu; katalog: Hatalar.

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

Test

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

Sorun giderme

BelirtiNeden / çözüm
iOS'ta abonelik oluşmuyorAppDelegate'te capacitorDidRegisterForRemoteNotifications bildirimi gönderilmiyor veya Push Notifications yeteneği eksik.
Tıklama/ön plan olayı gelmiyor@capacitor/push-notifications ya da başka bir push eklentisi UNUserNotificationCenter delegesini devralıyor; kaldırın.
Android: pushizo-android çözümlenemiyorpublishToMavenLocal çalıştırılmadı veya mavenLocal() deposu eklenmedi.
Bildirimden açılışta tıklama kayboluyoraddClickListener'ı initialize'dan önce, uygulama açılışında ekleyin.
requestPermission hep falseAndroid 13+'ta izin reddedildi; iOS'ta Push yeteneği eksik. Diğer belirtiler: Android, iOS.

Bu sayfada