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
Promisedöndürür; olay dinleyicisi ekleyen heradd…ç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)
- Firebase konsolunda Android uygulaması ekleyin,
google-services.jsondosyasınıandroid/app/altına koyun. Capacitor şablonucom.google.gms.google-serviceseklentisini dosya varsa otomatik uygular. - Dashboard → Kanallar → Android Push → Firebase servis hesabı JSON'u (kurulum sihirbazında Capacitor/Ionic seçilebilir).
- Eklenti
com.pushizo:pushizo-androidartefaktına bağlıdır; sürümvariables.gradleiçindepushizoAndroidVersionile değiştirilebilir. Maven Central yayınından önce monorepo içinden:cd sdk/android && gradle :pushizo:publishToMavenLocalveandroid/build.gradle→allprojects.repositoriesiçinemavenLocal(). POST_NOTIFICATIONS, FCM servisi ve bildirim açma Activity'si SDK manifestinden birleşir. Bildirim ikonu:AndroidManifest.xmliçindecom.pushizo.sdk.default_notification_iconmeta-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)
- Xcode → Signing & Capabilities: Push Notifications, Background Modes → Remote notifications.
- Dashboard → Kanallar → iOS Push →
.p8anahtarı (Key ID, Team ID, bundle id) veya.p12sertifikası. - 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)
}- CocoaPods:
npx cap sync ioseklentininPushizoCapacitorpod'unu kurar; bu pod CocoaPods trunk'takiPushizopod'una (~> 0.1) bağımlıdır,ios/App/Podfileiçine ayrıca satır eklemeniz gerekmez. SPM (Capacitor 7): pakethttps://github.com/exec0de/pushizo-ios.gitdeposundan çözülür. - Zengin medya, rozet ve uygulama kapalıyken
receivedkaydı için Notification Service Extension hedefi (iOS 15) ekleyin, Podfile'atarget 'PushizoNSE' do pod 'Pushizo/Extension' endyazın veNotificationServicesı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'inePushizoAppGroupolarak yazın (verilmezsegroup.<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ılmazinitialize 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ı:
| Kod | Anlam |
|---|---|
INVALID_ARGUMENT | Geçersiz e-posta/telefon ya da eksik alan. |
NOT_READY | initialize çağrılmadı veya abonelik/kullanıcı henüz kayıtlı değil. |
NOT_FOUND | Ertelenen ön plan bildirimi bulunamadı ya da zaten gösterildi (event.display()). |
UNAVAILABLE | Web'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 buildSorun giderme
| Belirti | Neden / çözüm |
|---|---|
| iOS'ta abonelik oluşmuyor | AppDelegate'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ümlenemiyor | publishToMavenLocal çalıştırılmadı veya mavenLocal() deposu eklenmedi. |
| Bildirimden açılışta tıklama kayboluyor | addClickListener'ı initialize'dan önce, uygulama açılışında ekleyin. |
requestPermission hep false | Android 13+'ta izin reddedildi; iOS'ta Push yeteneği eksik. Diğer belirtiler: Android, iOS. |
React Native SDK
@pushizo/react-native — Android ve iOS yerel SDK'larını saran TurboModule köprüsü ve Expo config plugin; push, in-app, bildirim kutusu, tercihler.
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.