cordova-plugin-pushizo 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,350 +1,495 @@
1
- <!-- pushizo:header -->
2
- <p align="center">
3
- <a href="https://pushizo.com"><img src="https://raw.githubusercontent.com/pushizo/.github/main/profile/assets/mark.svg" alt="Pushizo" width="56" height="56"></a>
4
- </p>
5
- <p align="center">
6
- <a href="https://docs.pushizo.com/docs/sdk/cordova"><img src="https://img.shields.io/badge/docs-docs.pushizo.com-5b4bdb" alt="Docs"></a>
7
- <a href="https://docs.pushizo.com/docs/api"><img src="https://img.shields.io/badge/API-reference-b44fc4" alt="API reference"></a>
8
- <a href="https://github.com/pushizo/pushizo-cordova/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-16130f" alt="License: MIT"></a>
9
- </p>
10
- <p align="center"><a href="#english">English</a> · <a href="#türkçe">Türkçe</a></p>
11
-
12
- ## English
13
-
14
- **Pushizo Cordova plugin** — Cordova plugin that wraps the native Pushizo Android and iOS SDKs through cordova.exec.
15
-
16
- > **Status:** Publishing to npm is in progress.<br>
17
- > **Durum:** npm yayını hazırlanıyor.
18
-
19
- **Install from GitHub until then · O zamana kadar GitHub'dan kurulum:**
20
-
21
- ```bash
22
- cordova plugin add https://github.com/pushizo/pushizo-cordova.git#v0.1.0
23
- ```
24
-
25
- **After publication · Yayından sonra:**
26
-
27
- ```bash
28
- cordova plugin add cordova-plugin-pushizo
29
- ```
30
-
31
- The detailed guide below is in Turkish; code samples are language-neutral. Full documentation:
32
- [docs.pushizo.com/docs/sdk/cordova](https://docs.pushizo.com/docs/sdk/cordova) · API reference: [docs.pushizo.com/docs/api](https://docs.pushizo.com/docs/api).
33
-
34
- ## Türkçe
35
- <!-- /pushizo:header -->
36
-
37
- # cordova-plugin-pushizo
38
-
39
- Pushizo'nun Cordova eklentisi. Native Pushizo Android (`com.pushizo:pushizo-android`) ve iOS (`Pushizo` pod) SDK'larını `cordova.exec` köprüsüyle sarar. API yüzeyi plan 06 §6.1, eski sağlayıcı v5 ve `@pushizo/capacitor` ile aynıdır.
40
-
41
- - cordova ≥ 12, cordova-android ≥ 12 (minSdk 24), cordova-ios ≥ 7 (iOS 15+)
42
- - Push aboneliği (FCM/APNs), izin istemi ve izin gözlemcisi
43
- - Bildirim tıklaması (soğuk başlatma dahil), ön plan gösterimini engelleme/erteleme
44
- - Kullanıcı: `login`/`logout` (`identityHash`), tag, alias, dil, e-posta ve SMS aboneliği
45
- - In-app mesajlar (tetik, ekran, duraklatma, tıklama ve yaşam döngüsü olayları; native çizim)
46
- - Konum paylaşımı (yalnızca ön plan, açıklama + izin istemi)
47
- - Bildirim kutusu, özel olay, KVKK/GDPR gizlilik onayı, günlük seviyesi, bildirim tepsisini temizleme
48
-
49
- ## Kurulum
50
-
51
- ```bash
52
- cordova plugin add cordova-plugin-pushizo
53
- # monorepo içinden:
54
- cordova plugin add ../../sdk/cordova
55
- ```
56
-
57
- Eklenti JS'i `window.Pushizo` ve `window.plugins.Pushizo` olarak yüklenir. TypeScript için tipler pakettedir (`types/index.d.ts`).
58
-
59
- ## Kullanım
60
-
61
- ```js
62
- document.addEventListener('deviceready', async () => {
63
- // Tıklama dinleyicisini erken ekleyin; uygulama bildirimden açıldıysa tıklama ilk dinleyiciye teslim edilir.
64
- Pushizo.Notifications.addClickListener((event) => {
65
- console.log(event.notification.title, event.result.actionId, event.result.url);
66
- });
67
-
68
- await Pushizo.initialize('app_xxx', { apiUrl: 'https://api.pushizo.com', logLevel: 'warn' });
69
- await Pushizo.Notifications.requestPermission();
70
- await Pushizo.login('user_42'); // identity verification açıksa: login('user_42', identityHash)
71
- await Pushizo.User.addTags({ plan: 'pro', level: 3 });
72
- await Pushizo.User.addEmail('ali@pushizo.com');
73
- await Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9);
74
- });
75
- ```
76
-
77
- Tüm metotlar Promise döndürür. Hatalar `PushizoError` örneğidir ve `code` alanı taşır: `INVALID_ARGUMENT`, `NOT_READY`, `NOT_FOUND`, `NOT_IMPLEMENTED` veya sunucu hata kodu.
78
-
79
- ### JWT ile kimlik doğrulama
80
-
81
- App ayarlarında kimlik doğrulama kipi (`identity_verification_mode`) `jwt` veya `both` ise kullanıcı, sunucunuzda
82
- imzalanmış kısa ömürlü bir ES256 JWT ile kimliklendirilir (talepler: `sub` = external_id, `aud` = app_id, `exp`/`iat` zorunlu, en çok 24 saat, yalnızca ES256).
83
-
84
- ```js
85
- await Pushizo.login('user_42', { jwt: jwtFromBackend }); // yalnızca JWT
86
- await Pushizo.login('user_42', { identityHash: hmac, jwt: jwtFromBackend }); // both kipinde ikisi birlikte
87
- await Pushizo.updateUserJwt(refreshedJwt); // süresi dolmadan yenileyin
88
- await Pushizo.logout();
89
- ```
90
-
91
- - JWT yerel SDK'da identity hash ile aynı kalıcı depoda saklanır ve tüm `/sdk/v1/...` isteklerinde
92
- `Authorization: Bearer <jwt>` başlığıyla gider; gövdeye/URL'ye yazılmaz, loglanmaz. `logout` belirteci siler.
93
- - `/config` yanıtında `identity_verification_required` true ise login öncesi kanıt denetlenir: `jwt` kipinde JWT, `hmac`
94
- kipinde `identityHash` zorunludur, `both` kipinde biri yeter; eksikse `login` `NOT_READY` ile reddedilir. Alan gelmeyen
95
- eski sunucularda kip `hmac` sayılır; ikinci argümanı metin olan eski `login(id, identityHash)` çağrıları aynen çalışır.
96
- - `updateUserJwt` giriş yapılmamışsa `NOT_READY` ile reddedilir; başarıda kuyrukta bekleyen işlemler yeni belirteçle
97
- yeniden denenir.
98
-
99
- ### Live Activities (iOS)
100
-
101
- Köprü, iOS SDK'nın genel `PushizoDefaultLiveActivityAttributes` türünü kullanır "Live Activities"). Sunucu etkinliği uzaktan başlatır (push-to-start, iOS 17.2+), günceller ve bitirir;
102
- yerel başlatma iOS 16.1+ ister.
103
-
104
- ```js
105
- await Pushizo.initialize('app_xxx');
106
- await Pushizo.LiveActivities.setupDefaultLiveActivity(); // her açılışta: belirteçler sunucuya kaydedilir
107
- await Pushizo.LiveActivities.startDefaultLiveActivity(
108
- 'order_42', // 1-100 karakter: harf, rakam, _ . : -
109
- { title: 'Sipariş #42' }, // attributes ('pushizo' anahtarı ayrılmıştır)
110
- { status: 'Yolda', eta: 12 }, // contentState
111
- );
112
- ```
113
-
114
- - Değerler metin, sonlu sayı veya boolean; anahtarlar 1-64 karakter. Kurala uymayan girdi köprüye gitmeden `TypeError`/
115
- `RangeError` fırlatır.
116
- - Hata kodları (`PushizoError.code`): `PLATFORM_NOT_SUPPORTED` (iOS 16.1 öncesi; Android'de her zaman), `NOT_READY`
117
- (`initialize` yok), `INVALID_ARGUMENT`, `LIVE_ACTIVITY_FAILED` (Live Activities kapalı, `NSSupportsLiveActivities` yok,
118
- sistem sınırı).
119
- - Xcode: uygulamanın Info.plist'ine `NSSupportsLiveActivities = YES` ekleyin; **Widget Extension** hedefi oluşturun ve
120
- hedefe SPM'de `PushizoExtension` ürününü (`import PushizoExtension`), CocoaPods'ta `pod 'Pushizo/Extension'`
121
- (`import Pushizo`) ekleyin:
122
-
123
- ```swift
124
- ActivityConfiguration(for: PushizoDefaultLiveActivityAttributes.self) { context in
125
- VStack {
126
- Text(context.attributes.data["title"]?.stringValue ?? "")
127
- Text(context.state.data["status"]?.description ?? "")
128
- }
129
- } dynamicIsland: { context in
130
- DynamicIsland { DynamicIslandExpandedRegion(.center) { Text(context.state.data["status"]?.description ?? "") } }
131
- compactLeading: { EmptyView() } compactTrailing: { Text(context.state.data["eta"]?.description ?? "") } minimal: { EmptyView() }
132
- }
133
- ```
134
-
135
- - Dashboard'da (**Live Activities**) veya API'de tür adı tam olarak `PushizoDefaultLiveActivityAttributes` olmalıdır.
136
- Sunucu: `POST /v1/apps/{appId}/live-activities/PushizoDefaultLiveActivityAttributes/start` (`activity_id`,
137
- `attributes`, `content_state`, `target`), `…/update` ve `…/end` (`activity_id`, `content_state`).
138
- - Tip-güvenli kendi türünüz için native tarafta `Pushizo.LiveActivities.register(MyAttributes.self)` kullanın.
139
-
140
- ### Canlı sohbet
141
-
142
- ```ts
143
- await Pushizo.Chat.start({ name: 'Ali' });
144
- const config = await Pushizo.Chat.getConfig(); // online, offlineMessage, ek sınırları
145
- const { messages } = await Pushizo.Chat.getMessages();
146
- Pushizo.Chat.addEventListener('message', ({ message }) => render(message));
147
- Pushizo.Chat.addEventListener('open', ({ conversationId }) => openChat(conversationId)); // bildirime tıklama
148
- await Pushizo.Chat.startListening(); // ekran açıkken; ayrılınca stopListening()
149
- await Pushizo.Chat.sendMessage('Merhaba'); // bot hızlı yanıtı: sendMessage(label, { optionId })
150
- await Pushizo.Chat.sendAttachment({ base64 }, { fileName: 'a.png', mimeType: 'image/png' });
151
- await Pushizo.Chat.markRead(messages[messages.length - 1].seq);
152
- ```
153
-
154
- Ziyaretçi kimliği, çevrimdışı kuyruk (aynı `client_message_id` ile yeniden deneme), canlı akış (SSE; koparsa üstel
155
- geri çekilme + `after_seq` yoklaması) ve push ile gelen temsilci mesajları (`pushizo_chat`) yerel Android/iOS SDK'sındadır;
156
- `start` sonrası login/logout ve push aboneliği değişince bağlama yerel SDK'da yenilenir, logout ziyaretçiyi sıfırlar.
157
- Mesajlar `seq` ile sıralanır; ağ yokken gönderilen mesaj `pending` döner ve gönderilince olayla sunucu kopyası gelir.
158
- Ayrıntı: [android rehberi](https://docs.pushizo.com/docs/sdk/android) / [ios rehberi](https://docs.pushizo.com/docs/sdk/ios) → "Canlı sohbet".
159
-
160
- ### Konum
161
-
162
- Kullanıcı izin verirse cihazın konumu push aboneliğine yazılır; segmentlerde konuma göre hedefleme için
163
- kullanılır. Paylaşım **yalnızca ön planda** çalışır (arka plan konumu yok): native SDK konumu oturum başında ve uygulama
164
- ön plana döndüğünde en sık 5 dakikada bir gönderir. İzin yoksa veya gizlilik onayı (`requiresPrivacyConsent`)
165
- verilmemişse hiçbir şey gönderilmez; tercih kalıcıdır.
166
-
167
- ```js
168
- const granted = await Pushizo.Location.requestPermission('Yakındaki mağazaları göstermek için konumunuzu kullanırız.');
169
- if (granted) await Pushizo.Location.setShared(true);
170
- const shared = await Pushizo.Location.isShared(); // kalıcı tercih (izin durumundan bağımsız)
171
- await Pushizo.Location.setShared(false); // paylaşımı kapatır, sunucudaki konumu siler
172
- ```
173
-
174
- - `requestPermission(rationale?)`: izin yoksa önce açıklama gösterilir (`rationale`; verilmezse SDK'nın Türkçe/İngilizce
175
- varsayılan metni), kullanıcı "Şimdi değil" derse sistem istemi açılmaz. İzin varsa veya verildiyse `true`; reddedildiyse,
176
- uygulama izni tanımlamadıysa ya da vazgeçildiyse `false`. `isShared()` native SDK'daki özelliğin asenkron karşılığıdır.
177
- - `initialize` öncesinde `setShared`/`requestPermission` `NOT_READY` koduyla reddedilir.
178
- - **KVKK:** sunucuya ulaşan ilk konum açık rıza kaydı olarak saklanır. Kullanıcıya konumun neden kullanıldığını
179
- açıklayın ve paylaşımı yalnızca onayıyla açın. `setShared(false)` sunucuya `location: null` gönderir; konum ve rıza
180
- kaydı silinir, henüz gönderilmemiş konum atılır.
181
- - **iOS:** `Info.plist` dosyasına `NSLocationWhenInUseUsageDescription` ekleyin (yoksa `requestPermission` `false` döner);
182
- `config.xml` içinde `<platform name="ios">` altına
183
- `<edit-config file="*-Info.plist" target="NSLocationWhenInUseUsageDescription" mode="merge"><string>…</string></edit-config>`. Yalnızca "Uygulamayı Kullanırken" izni istenir; "Her Zaman" istenmez. Reddedilmiş izin yeniden
184
- sorulamaz, kullanıcı Ayarlar'a yönlendirilmelidir.
185
- - **Android:** eklenti konum iznini manifest'e **otomatik eklemez**; uygulamanın `config.xml` dosyasına kendiniz ekleyin
186
- (yaklaşık konum yeterlidir, hassas konum isteğe bağlıdır; `<widget>` öğesinde
187
- `xmlns:android="http://schemas.android.com/apk/res/android"` tanımlı olmalıdır):
188
-
189
- ```xml
190
- <platform name="android">
191
- <config-file target="AndroidManifest.xml" parent="/manifest">
192
- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
193
- <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
194
- </config-file>
195
- </platform>
196
- ```
197
-
198
- Yalnızca manifest'te tanımlı izinler istenir; hiçbiri yoksa uyarı loglanır ve `false` döner. Açıklama diyaloğu SDK'nın
199
- string kaynaklarını kullanır; sistem izni `cordova.requestPermissions` ile (`Pushizo.Location.PERMISSION_REQUEST_CODE`)
200
- istenir ve sonuç SDK'ya iletilir.
201
-
202
- ### Olaylar
203
-
204
- ```js
205
- Pushizo.Notifications.addForegroundLifecycleListener((event) => {
206
- event.preventDefault(); // ön planda gösterme; sonra göstermek için: event.display()
207
- });
208
- Pushizo.Notifications.addPermissionObserver(({ permission }) => {});
209
- Pushizo.User.pushSubscription.addObserver((state) => {}); // { id, token, optedIn, permission }
210
- Pushizo.InAppMessages.addClickListener((e) => {}); // { message: { id }, result: { actionId, url } }
211
- Pushizo.InAppMessages.addLifecycleListener({ willDisplay() {}, didDismiss() {} });
212
- ```
213
-
214
- `addPermissionObserver` olayları yerel Android/iOS SDK izin gözlemcisinden gelir (izin isteği sonucu ve uygulama ön plana
215
- döndüğünde ayarlardan yapılan değişiklik; yalnızca gerçek değişiklikte).
216
-
217
- Her `add…` çağrısı aboneliği kaldıran bir fonksiyon döndürür. Olaylar native taraftan tek bir `keepCallback` kanalıyla gelir; kanal açılmadan oluşan olaylar (ör. soğuk başlatma tıklaması) native tarafta tamponlanır.
218
-
219
- ### In-app, bildirim kutusu ve diğerleri
220
-
221
- ```js
222
- await Pushizo.InAppMessages.addTrigger('level', 5);
223
- await Pushizo.InAppMessages.setScreen('checkout');
224
- await Pushizo.InAppMessages.setPaused(false);
225
-
226
- const page = await Pushizo.Inbox.list({ limit: 20 }); // { items, unreadCount, nextCursor, hasMore }
227
- await Pushizo.Inbox.markRead(page.items[0].id);
228
- await Pushizo.Inbox.markAllRead();
229
- await Pushizo.Inbox.archive(page.items[0].id);
230
-
231
- // Tercihler (kategori × kanal opt-in; channel verilmezse tüm kanallar). Abonelik yoksa NOT_READY.
232
- const { preferences, categories } = await Pushizo.User.getPreferences();
233
- await Pushizo.User.setPreferences([
234
- { category: 'promo', optedIn: false },
235
- { category: 'news', channel: 'email', optedIn: true },
236
- ]); // güncel listeyi döndürür
237
-
238
- await Pushizo.Notifications.clearAll();
239
- await Pushizo.Notifications.removeGroupedNotifications('orders');
240
- await Pushizo.Notifications.removeNotification(id); // Android: notification.androidNotificationId; iOS: UNNotificationRequest.identifier (metin)
241
- await Pushizo.setConsentGiven(true); // requiresPrivacyConsent: true ile başlatıldıysa
242
- await Pushizo.Debug.setLogLevel('debug');
243
- await Pushizo.logout();
244
- ```
245
-
246
- ### HTML in-app ve carousel
247
-
248
- In-app mesajları yerel Android/iOS SDK'sı çizer; bu paket köprüdür. HTML in-app (sandbox'lı WebView, köprü
249
- `close`/`click`/`addTag`/`trackEvent`) ve carousel blokları yerel SDK'dan olduğu gibi devralınır: ek kod veya
250
- yapılandırma gerekmez, tıklama ve yaşam döngüsü olayları mevcut in-app dinleyicilerine gelir. Yetenek bildirimi
251
- (`supports=html,carousel`) yerel SDK tarafından yapılır; desteklemeyen eski yerel sürümlere sunucu HTML mesaj göndermez
252
- ve carousel bloklarını çıkarır.
253
-
254
- ## Android kurulumu (FCM)
255
-
256
- 1. Firebase konsolunda Android uygulaması ekleyin; `google-services.json` dosyasını proje köküne koyun ve `config.xml` içine ekleyin:
257
-
258
- ```xml
259
- <platform name="android">
260
- <preference name="GradlePluginKotlinEnabled" value="true" />
261
- <preference name="GradlePluginGoogleServicesEnabled" value="true" />
262
- <preference name="GradlePluginGoogleServicesVersion" value="4.4.2" />
263
- <resource-file src="google-services.json" target="app/google-services.json" />
264
- </platform>
265
- ```
266
-
267
- Köprü Kotlin ile yazıldığından `GradlePluginKotlinEnabled` zorunludur.
268
- 2. Pushizo dashboard'unda Firebase servis hesabı JSON'unu yükleyin (kurulum sihirbazında **Cordova** seçilebilir); kayıt sonrası otomatik doğrulanır.
269
- 3. Eklenti `com.pushizo:pushizo-android` artefaktına bağlıdır. Maven Central yayınına kadar `sdk/android` içinde `gradle :pushizo:publishToMavenLocal` çalıştırın; eklenti `mavenLocal()` deposunu ekler.
270
- 4. FCM servisi, `POST_NOTIFICATIONS` izni ve bildirim Activity'si SDK manifestinden birleşir. Bildirim ikonu için `AndroidManifest.xml` içinde `com.pushizo.sdk.default_notification_icon` meta-data'sı verilebilir.
271
-
272
- Eklenti, JS ile yapılan `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.
273
-
274
- ## iOS kurulumu (APNs)
275
-
276
- 1. `config.xml`:
277
-
278
- ```xml
279
- <platform name="ios">
280
- <preference name="deployment-target" value="15.0" />
281
- <preference name="SwiftVersion" value="5" />
282
- </platform>
283
- ```
284
-
285
- 2. Eklenti Push Notifications yetkisini (`aps-environment`) ve `remote-notification` arka plan modunu ekler. Pushizo dashboard'unda APNs `.p8` anahtarını veya `.p12` sertifikasını yükleyin.
286
- 3. `Pushizo` pod'u yayınlanana kadar `platforms/ios/Podfile` içinde `pod 'Pushizo', :path => '<repo>/sdk/ios'` kullanın ve `pod install` çalıştırın.
287
- 4. APNs token geri çağrıları (`didRegisterForRemoteNotificationsWithDeviceToken`/`didFailToRegister…`) eklenti yüklenirken AppDelegate sınıfına çalışma zamanında eklenir; AppDelegate'te bu metotlar varsa önce SDK'ya iletilir, sonra sizin kodunuz çalışır.
288
- 5. Pushizo SDK'sı `UNUserNotificationCenter` delegesini üstlenir; başka bir push eklentisiyle (ör. `cordova-plugin-firebasex`) birlikte kullanmayın.
289
-
290
- ### Notification Service Extension (zengin medya, teslim bildirimi)
291
-
292
- Resimli bildirimler, rozet artışı ve uygulama kapalıyken `received` bildirimi için Xcode'da (`platforms/ios/*.xcworkspace`) **File → New → Target → Notification Service Extension** ekleyin (iOS 15), Podfile'a hedefi ekleyin:
293
-
294
- ```ruby
295
- target 'PushizoNSE' do
296
- pod 'Pushizo/Extension', :path => '<repo>/sdk/ios'
297
- end
298
- ```
299
-
300
- ve `NotificationService.swift` dosyasını SDK yardımcısına devredin:
301
-
302
- ```swift
303
- import UserNotifications
304
- import Pushizo
305
-
306
- class NotificationService: UNNotificationServiceExtension {
307
- let hs = PushizoNotificationServiceExtension(appId: "app_xxx", apiUrl: "https://api.pushizo.com",
308
- appGroup: "group.com.pushizo.app.pushizo")
309
-
310
- override func didReceive(_ request: UNNotificationRequest, withContentHandler handler: @escaping (UNNotificationContent) -> Void) {
311
- hs.didReceive(request, withContentHandler: handler)
312
- }
313
-
314
- override func serviceExtensionTimeWillExpire() { hs.serviceExtensionTimeWillExpire() }
315
- }
316
- ```
317
-
318
- Uygulama ve NSE hedeflerinde aynı App Group yeteneğini açın ve uygulamanın `Info.plist` dosyasına `PushizoAppGroup` anahtarıyla yazın (rozet sayacı paylaşımı). `cordova platform rm/add ios` Xcode projesini yeniden oluşturduğundan NSE hedefi yeniden eklenmelidir.
319
-
320
- ## Geliştirme
321
-
322
- ```bash
323
- npm install
324
- npm run typecheck
325
- npm test # vitest: cephe, cordova.exec köprüsü ve native sözleşme denetimi
326
- npm run build # src/*.ts → www/*.js (eklentiyle birlikte yayınlanır, depoda tutulur)
327
- ```
328
-
329
- Adım adım kurulum ve örnek kod: [cordova rehberi](https://docs.pushizo.com/docs/sdk/cordova).
330
-
331
- <!-- pushizo:footer -->
332
- ---
333
-
334
- ## Support · Destek
335
-
336
- - **Guide · Rehber:** [docs.pushizo.com/docs/sdk/cordova](https://docs.pushizo.com/docs/sdk/cordova)
337
- - **API reference & OpenAPI · API referansı ve OpenAPI:** [docs.pushizo.com/docs/api](https://docs.pushizo.com/docs/api) ·
338
- [pushizo-openapi](https://github.com/pushizo/pushizo-openapi)
339
- - **Bugs & ideas · Hata ve öneri:** [Issues](https://github.com/pushizo/pushizo-cordova/issues)
340
- - **Security · Güvenlik:** please do not open public issues; email [security@pushizo.com](mailto:security@pushizo.com) ·
341
- herkese açık issue açmayın, bu adrese yazın.
342
- - **Help · Destek:** [support@pushizo.com](mailto:support@pushizo.com)
343
-
344
- This repository is mirrored automatically from the Pushizo main repository on every release. Please open an issue
345
- instead of a pull request; fixes land in the main repository and ship with the next release.
346
- Bu depo her sürümde Pushizo ana deposundan otomatik yansıtılır. Pull request yerine issue açın; düzeltmeler ana depoda
347
- yapılır ve bir sonraki sürümle buraya gelir.
348
-
349
- Released under the MIT License · MIT lisanslıdır — [LICENSE](https://github.com/pushizo/pushizo-cordova/blob/main/LICENSE).
350
- <!-- /pushizo:footer -->
1
+ <!-- pushizo:header -->
2
+ <p align="center">
3
+ <a href="https://pushizo.com"><img src="https://raw.githubusercontent.com/pushizo/.github/main/profile/assets/mark.svg" alt="Pushizo" width="56" height="56"></a>
4
+ </p>
5
+ <p align="center">
6
+ <a href="https://docs.pushizo.com/docs/sdk/cordova"><img src="https://img.shields.io/badge/docs-docs.pushizo.com-5b4bdb" alt="Docs"></a>
7
+ <a href="https://docs.pushizo.com/docs/api"><img src="https://img.shields.io/badge/API-reference-b44fc4" alt="API reference"></a>
8
+ <a href="https://github.com/pushizo/pushizo-cordova/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-16130f" alt="License: MIT"></a>
9
+ </p>
10
+ <p align="center"><a href="#english">English</a> · <a href="#türkçe">Türkçe</a></p>
11
+
12
+ ## English
13
+
14
+ **Pushizo Cordova plugin** — Cordova plugin that wraps the native Pushizo Android and iOS SDKs through cordova.exec.
15
+
16
+ ```bash
17
+ cordova plugin add cordova-plugin-pushizo
18
+ ```
19
+
20
+ The detailed guide below is in Turkish; code samples are language-neutral. Full documentation:
21
+ [docs.pushizo.com/docs/sdk/cordova](https://docs.pushizo.com/docs/sdk/cordova) · API reference: [docs.pushizo.com/docs/api](https://docs.pushizo.com/docs/api).
22
+
23
+ ## Türkçe
24
+ <!-- /pushizo:header -->
25
+
26
+ # cordova-plugin-pushizo
27
+
28
+ Pushizo'nun Cordova eklentisi. Native Pushizo Android (`com.pushizo:pushizo-android`) ve iOS (`Pushizo` pod) SDK'larını `cordova.exec` köprüsüyle sarar. API yüzeyi plan 06 §6.1, eski sağlayıcı v5 ve `@pushizo/capacitor` ile aynıdır.
29
+
30
+ - cordova ≥ 12, cordova-android ≥ 12 (minSdk 24), cordova-ios ≥ 7 (iOS 15+)
31
+ - Push aboneliği (FCM/APNs), izin istemi ve izin gözlemcisi
32
+ - Bildirim tıklaması (soğuk başlatma dahil), ön plan gösterimini engelleme/erteleme
33
+ - Kullanıcı: `login`/`logout` (`identityHash`), tag, alias, dil, e-posta ve SMS aboneliği
34
+ - In-app mesajlar (tetik, ekran, duraklatma, tıklama ve yaşam döngüsü olayları; native çizim)
35
+ - Konum paylaşımı (yalnızca ön plan, açıklama + izin istemi) ve arka plan bölge izleme
36
+ - Özellik bayrakları (`FeatureFlags`) ve gömülü yerleşimler (`Placements`)
37
+ - Android teslimat güçlendirme (`Delivery`: üretici/ROM teşhisi, ayar ekranına yönlendirme; iOS'ta zararsız)
38
+ - Profille `login`, reklam kişiselleştirme rızası (`setAdsPersonalizationConsent`, `getConsents`), reklam kimliği (`Ads`), rozet, arka plan konum izni
39
+ - Kullanıcı özellikleri (`User.setProperty`), özellik bayrağı ve bildirim kutusu gözlemcileri, olay tekilleştirme kimliği (`eventId`), hazır sohbet ekranı (`Chat.show`)
40
+ - Bildirim kutusu, özel olay, KVKK/GDPR gizlilik onayı, günlük seviyesi, bildirim tepsisini temizleme
41
+
42
+ ## Kurulum
43
+
44
+ ```bash
45
+ cordova plugin add cordova-plugin-pushizo
46
+ # monorepo içinden:
47
+ cordova plugin add ../../sdk/cordova
48
+ ```
49
+
50
+ Eklenti JS'i `window.Pushizo` ve `window.plugins.Pushizo` olarak yüklenir. TypeScript için tipler pakettedir (`types/index.d.ts`).
51
+
52
+ ## Kullanım
53
+
54
+ ```js
55
+ document.addEventListener('deviceready', async () => {
56
+ // Tıklama dinleyicisini erken ekleyin; uygulama bildirimden açıldıysa tıklama ilk dinleyiciye teslim edilir.
57
+ Pushizo.Notifications.addClickListener((event) => {
58
+ console.log(event.notification.title, event.result.actionId, event.result.url);
59
+ });
60
+
61
+ await Pushizo.initialize('app_xxx', { apiUrl: 'https://api.pushizo.com', logLevel: 'warn' });
62
+ await Pushizo.Notifications.requestPermission();
63
+ await Pushizo.login('user_42'); // identity verification açıksa: login('user_42', identityHash)
64
+ await Pushizo.User.addTags({ plan: 'pro', level: 3 });
65
+ await Pushizo.User.addEmail('ali@pushizo.com');
66
+ await Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9);
67
+ });
68
+ ```
69
+
70
+ Tüm metotlar Promise döndürür. Hatalar `PushizoError` örneğidir ve `code` alanı taşır: `INVALID_ARGUMENT`, `NOT_READY`, `NOT_FOUND`, `NOT_IMPLEMENTED` veya sunucu hata kodu.
71
+
72
+ ### JWT ile kimlik doğrulama
73
+
74
+ App ayarlarında kimlik doğrulama kipi (`identity_verification_mode`) `jwt` veya `both` ise kullanıcı, sunucunuzda
75
+ imzalanmış kısa ömürlü bir ES256 JWT ile kimliklendirilir (talepler: `sub` = external_id, `aud` = app_id, `exp`/`iat` zorunlu, en çok 24 saat, yalnızca ES256).
76
+
77
+ ```js
78
+ await Pushizo.login('user_42', { jwt: jwtFromBackend }); // yalnızca JWT
79
+ await Pushizo.login('user_42', { identityHash: hmac, jwt: jwtFromBackend }); // both kipinde ikisi birlikte
80
+ await Pushizo.updateUserJwt(refreshedJwt); // süresi dolmadan yenileyin
81
+ await Pushizo.logout();
82
+ ```
83
+
84
+ - JWT yerel SDK'da identity hash ile aynı kalıcı depoda saklanır ve tüm `/sdk/v1/...` isteklerinde
85
+ `Authorization: Bearer <jwt>` başlığıyla gider; gövdeye/URL'ye yazılmaz, loglanmaz. `logout` belirteci siler.
86
+ - `/config` yanıtında `identity_verification_required` true ise login öncesi kanıt denetlenir: `jwt` kipinde JWT, `hmac`
87
+ kipinde `identityHash` zorunludur, `both` kipinde biri yeter; eksikse `login` `NOT_READY` ile reddedilir. Alan gelmeyen
88
+ eski sunucularda kip `hmac` sayılır; ikinci argümanı metin olan eski `login(id, identityHash)` çağrıları aynen çalışır.
89
+ - `updateUserJwt` giriş yapılmamışsa `NOT_READY` ile reddedilir; başarıda kuyrukta bekleyen işlemler yeni belirteçle
90
+ yeniden denenir.
91
+
92
+ ### Live Activities (iOS)
93
+
94
+ Köprü, iOS SDK'nın genel `PushizoDefaultLiveActivityAttributes` türünü kullanır "Live Activities"). Sunucu etkinliği uzaktan başlatır (push-to-start, iOS 17.2+), günceller ve bitirir;
95
+ yerel başlatma iOS 16.1+ ister.
96
+
97
+ ```js
98
+ await Pushizo.initialize('app_xxx');
99
+ await Pushizo.LiveActivities.setupDefaultLiveActivity(); // her açılışta: belirteçler sunucuya kaydedilir
100
+ await Pushizo.LiveActivities.startDefaultLiveActivity(
101
+ 'order_42', // 1-100 karakter: harf, rakam, _ . : -
102
+ { title: 'Sipariş #42' }, // attributes ('pushizo' anahtarı ayrılmıştır)
103
+ { status: 'Yolda', eta: 12 }, // contentState
104
+ );
105
+ ```
106
+
107
+ - Değerler metin, sonlu sayı veya boolean; anahtarlar 1-64 karakter. Kurala uymayan girdi köprüye gitmeden `TypeError`/
108
+ `RangeError` fırlatır.
109
+ - Hata kodları (`PushizoError.code`): `PLATFORM_NOT_SUPPORTED` (iOS 16.1 öncesi; Android'de her zaman), `NOT_READY`
110
+ (`initialize` yok), `INVALID_ARGUMENT`, `LIVE_ACTIVITY_FAILED` (Live Activities kapalı, `NSSupportsLiveActivities` yok,
111
+ sistem sınırı).
112
+ - Xcode: uygulamanın Info.plist'ine `NSSupportsLiveActivities = YES` ekleyin; **Widget Extension** hedefi oluşturun ve
113
+ hedefe SPM'de `PushizoExtension` ürününü (`import PushizoExtension`), CocoaPods'ta `pod 'Pushizo/Extension'`
114
+ (`import Pushizo`) ekleyin:
115
+
116
+ ```swift
117
+ ActivityConfiguration(for: PushizoDefaultLiveActivityAttributes.self) { context in
118
+ VStack {
119
+ Text(context.attributes.data["title"]?.stringValue ?? "")
120
+ Text(context.state.data["status"]?.description ?? "")
121
+ }
122
+ } dynamicIsland: { context in
123
+ DynamicIsland { DynamicIslandExpandedRegion(.center) { Text(context.state.data["status"]?.description ?? "") } }
124
+ compactLeading: { EmptyView() } compactTrailing: { Text(context.state.data["eta"]?.description ?? "") } minimal: { EmptyView() }
125
+ }
126
+ ```
127
+
128
+ - Dashboard'da (**Live Activities**) veya API'de tür adı tam olarak `PushizoDefaultLiveActivityAttributes` olmalıdır.
129
+ Sunucu: `POST /v1/apps/{appId}/live-activities/PushizoDefaultLiveActivityAttributes/start` (`activity_id`,
130
+ `attributes`, `content_state`, `target`), `…/update` ve `…/end` (`activity_id`, `content_state`).
131
+ - Tip-güvenli kendi türünüz için native tarafta `Pushizo.LiveActivities.register(MyAttributes.self)` kullanın.
132
+
133
+ ### Canlı sohbet
134
+
135
+ ```ts
136
+ await Pushizo.Chat.start({ name: 'Ali' });
137
+ const config = await Pushizo.Chat.getConfig(); // online, offlineMessage, ek sınırları
138
+ const { messages } = await Pushizo.Chat.getMessages();
139
+ Pushizo.Chat.addEventListener('message', ({ message }) => render(message));
140
+ Pushizo.Chat.addEventListener('open', ({ conversationId }) => openChat(conversationId)); // bildirime tıklama
141
+ await Pushizo.Chat.startListening(); // ekran açıkken; ayrılınca stopListening()
142
+ await Pushizo.Chat.sendMessage('Merhaba'); // bot hızlı yanıtı: sendMessage(label, { optionId })
143
+ await Pushizo.Chat.sendAttachment({ base64 }, { fileName: 'a.png', mimeType: 'image/png' });
144
+ await Pushizo.Chat.markRead(messages[messages.length - 1].seq);
145
+ ```
146
+
147
+ Ziyaretçi kimliği, çevrimdışı kuyruk (aynı `client_message_id` ile yeniden deneme), canlı akış (SSE; koparsa üstel
148
+ geri çekilme + `after_seq` yoklaması) ve push ile gelen temsilci mesajları (`pushizo_chat`) yerel Android/iOS SDK'sındadır;
149
+ `start` sonrası login/logout ve push aboneliği değişince bağlama yerel SDK'da yenilenir, logout ziyaretçiyi sıfırlar.
150
+ Mesajlar `seq` ile sıralanır; ağ yokken gönderilen mesaj `pending` döner ve gönderilince olayla sunucu kopyası gelir.
151
+ Ayrıntı: [android rehberi](https://docs.pushizo.com/docs/sdk/android) / [ios rehberi](https://docs.pushizo.com/docs/sdk/ios) → "Canlı sohbet".
152
+
153
+ Hazır sohbet ekranı için kendi arayüzünüzü yazmanız gerekmez: `Pushizo.Chat.show()` yerel SDK'nın sohbet ekranını açar (Android `HsChatActivity`, iOS modal `HSChatViewController`), `Pushizo.Chat.hide()` kapatır, `Pushizo.Chat.isPresented()` ekranın açık olup olmadığını döndürür. Ayrıntı: "Kullanıcı özellikleri, gözlemciler, olay kimliği ve hazır sohbet ekranı".
154
+
155
+ ### Konum
156
+
157
+ Kullanıcı izin verirse cihazın konumu push aboneliğine yazılır; segmentlerde konuma göre hedefleme için
158
+ kullanılır. Paylaşım **yalnızca ön planda** çalışır (arka plan konumu yok): native SDK konumu oturum başında ve uygulama
159
+ ön plana döndüğünde en sık 5 dakikada bir gönderir. İzin yoksa veya gizlilik onayı (`requiresPrivacyConsent`)
160
+ verilmemişse hiçbir şey gönderilmez; tercih kalıcıdır.
161
+
162
+ ```js
163
+ const granted = await Pushizo.Location.requestPermission('Yakındaki mağazaları göstermek için konumunuzu kullanırız.');
164
+ if (granted) await Pushizo.Location.setShared(true);
165
+ const shared = await Pushizo.Location.isShared(); // kalıcı tercih (izin durumundan bağımsız)
166
+ await Pushizo.Location.setShared(false); // paylaşımı kapatır, sunucudaki konumu siler
167
+ ```
168
+
169
+ - `requestPermission(rationale?)`: izin yoksa önce açıklama gösterilir (`rationale`; verilmezse SDK'nın Türkçe/İngilizce
170
+ varsayılan metni), kullanıcı "Şimdi değil" derse sistem istemi açılmaz. İzin varsa veya verildiyse `true`; reddedildiyse,
171
+ uygulama izni tanımlamadıysa ya da vazgeçildiyse `false`. `isShared()` native SDK'daki özelliğin asenkron karşılığıdır.
172
+ - `initialize` öncesinde `setShared`/`requestPermission` `NOT_READY` koduyla reddedilir.
173
+ - **KVKK:** sunucuya ulaşan ilk konum açık rıza kaydı olarak saklanır. Kullanıcıya konumun neden kullanıldığını
174
+ açıklayın ve paylaşımı yalnızca onayıyla açın. `setShared(false)` sunucuya `location: null` gönderir; konum ve rıza
175
+ kaydı silinir, henüz gönderilmemiş konum atılır.
176
+ - **iOS:** `Info.plist` dosyasına `NSLocationWhenInUseUsageDescription` ekleyin (yoksa `requestPermission` `false` döner);
177
+ `config.xml` içinde `<platform name="ios">` altına
178
+ `<edit-config file="*-Info.plist" target="NSLocationWhenInUseUsageDescription" mode="merge"><string>…</string></edit-config>`. Yalnızca "Uygulamayı Kullanırken" izni istenir; "Her Zaman" istenmez. Reddedilmiş izin yeniden
179
+ sorulamaz, kullanıcı Ayarlar'a yönlendirilmelidir.
180
+ - **Android:** eklenti konum iznini manifest'e **otomatik eklemez**; uygulamanın `config.xml` dosyasına kendiniz ekleyin
181
+ (yaklaşık konum yeterlidir, hassas konum isteğe bağlıdır; `<widget>` öğesinde
182
+ `xmlns:android="http://schemas.android.com/apk/res/android"` tanımlı olmalıdır):
183
+
184
+ ```xml
185
+ <platform name="android">
186
+ <config-file target="AndroidManifest.xml" parent="/manifest">
187
+ <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
188
+ <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
189
+ </config-file>
190
+ </platform>
191
+ ```
192
+
193
+ Yalnızca manifest'te tanımlı izinler istenir; hiçbiri yoksa uyarı loglanır ve `false` döner. Açıklama diyaloğu SDK'nın
194
+ string kaynaklarını kullanır; sistem izni `cordova.requestPermissions` ile (`Pushizo.Location.PERMISSION_REQUEST_CODE`)
195
+ istenir ve sonuç SDK'ya iletilir.
196
+
197
+ ### Arka plan bölge izleme
198
+
199
+ Dashboard'da tanımlı coğrafi bölgelere giriş/çıkışı uygulama kapalıyken de yakalar ([ADR-0065](https://github.com/pushizo/pushizo/blob/main/docs/adr/0065-arka-plan-bolge-izleme.md)).
200
+ İzlemeyi işletim sistemi yapar; sunucuya koordinat gitmez, yalnızca giriş/çıkış olayı bildirilir. Varsayılan **kapalıdır**.
201
+
202
+ ```js
203
+ await Pushizo.Location.setGeofencingEnabled(true); // kalıcı tercih
204
+ const on = await Pushizo.Location.isGeofencingEnabled();
205
+ ```
206
+
207
+ - Üç koşul birlikte gerekir: `setGeofencingEnabled(true)`, `setShared(true)` ve arka plan konum izni (iOS "Her Zaman",
208
+ Android `ACCESS_BACKGROUND_LOCATION`). Köprü bu izni manifest/Info.plist'e **eklemez**; `Info.plist`'e `NSLocationAlwaysAndWhenInUseUsageDescription`, Android manifest'ine `ACCESS_BACKGROUND_LOCATION` eklemek
209
+ (`config.xml` `<config-file>`/`<edit-config>`) uygulamanın işidir. İzin `Location.requestBackgroundPermission()` ile istenir (aşağıda).
210
+ Mağaza beyanları ve aydınlatma metni uygulama geliştiricisinin sorumluluğundadır.
211
+ - `initialize` öncesinde `setGeofencingEnabled` `NOT_READY` ile reddedilir. `setShared(false)` veya gizlilik onayının geri
212
+ alınması kayıtlı bölgeleri kaldırır; tercih korunur.
213
+ - **Android:** uygulamada `com.google.android.gms:play-services-location` bağımlılığı bulunmalıdır; yoksa yerel SDK uyarı
214
+ loglar ve izleme başlamaz.
215
+
216
+ ### Özellik bayrakları
217
+
218
+ Bir özelliği yeni sürüm yayımlamadan açıp kapatın, kademeli yayın yapın veya metin/sayı/JSON değerleri uzaktan yönetin
219
+ ([rehber](https://docs.pushizo.com/docs/guides/feature-flags)). Değerler yerel SDK'da oturum başında yenilenir ve cihazda
220
+ saklanır; ağ yoksa son değer, hiç alınmadıysa koddaki varsayılan döner. Gizlilik onayı beklenirken istek gönderilmez.
221
+
222
+ ```js
223
+ if (await Pushizo.FeatureFlags.isEnabled('yeni_sepet')) showNewCart();
224
+ const limit = await Pushizo.FeatureFlags.getValue('sepet_limiti', 10); // metin, sayı, boolean, nesne veya dizi
225
+ const refreshed = await Pushizo.FeatureFlags.refresh(); // yeni değerler alındıysa true
226
+ ```
227
+
228
+ `isEnabled(key, default = false)` ve `getValue(key, default = null)` yerel önbellekten okur; köprü asenkron olduğundan
229
+ Promise döndürürler. Boş anahtar `TypeError` ile reddedilir.
230
+
231
+ ### Android teslimat güçlendirme
232
+
233
+ Xiaomi, Huawei, Oppo, Vivo ve Samsung gibi üreticilerde pil ve otomatik başlatma yöneticisi arka plandaki uygulamayı durdurur;
234
+ bildirim gecikir ya da gelmez ([rehber](https://docs.pushizo.com/docs/channels/android-delivery)). `Pushizo.Delivery` cihazdaki
235
+ kısıtları okur ve kullanıcıyı ilgili ayar ekranına götürür.
236
+
237
+ ```ts
238
+ const status = await Pushizo.Delivery.status(); // { supported, vendor, rom, risk, restricted, recommendedSettings, … }
239
+ if (await Pushizo.Delivery.shouldShowGuidance()) { // risk var ve diyalog son 14 günde gösterilmedi
240
+ const opened = await Pushizo.Delivery.showGuidance(); // hazır diyalog (22 dil); kabul edilirse ayar ekranı açılır
241
+ }
242
+ await Pushizo.Delivery.openSettings('auto_start'); // kendi arayüzünüzden
243
+ ```
244
+
245
+ | Metot | Açıklama |
246
+ |---|---|
247
+ | `Delivery.status()` | `Promise<DeliveryStatus>`: `supported`, `manufacturer`, `brand`, `vendor`, `aggressiveVendor`, `rom`, `romVersion`, `notificationsEnabled`, `channelBlocked`, `batteryOptimizationExempt`, `backgroundRestricted`, `standbyBucket`, `powerSaveMode`, `dataSaverEnabled`, `restricted`, `risk` (`none` \| `elevated` \| `high`), `recommendedSettings`. |
248
+ | `Delivery.shouldShowGuidance(minIntervalDays = 14)` | `Promise<boolean>`: teslim riski var ve hazır diyalog son `minIntervalDays` günde gösterilmedi. |
249
+ | `Delivery.openSettings(setting = 'auto')` | `Promise<boolean>`: ayar ekranı açıldı mı. `setting`: `auto` \| `notifications` \| `auto_start` \| `battery_optimization` \| `app_details`; üreticiye özgü ekran yoksa standart Android ekranına düşülür. |
250
+ | `Delivery.showGuidance({ setting?, message? })` | `Promise<boolean>`: hazır açıklama diyaloğu; kullanıcı kabul etti ve ayar ekranı açıldıysa `true`. SDK diyaloğu kendiliğinden göstermez. |
251
+
252
+ Yalnızca Android'de etkilidir: iOS'ta `status()` `supported: false` ve `risk: 'none'` döner, `openSettings` ile `showGuidance`
253
+ hiçbir şey yapmadan `false` döner. Köprü `REQUEST_IGNORE_BATTERY_OPTIMIZATIONS` iznini istemez ve manifest'e eklemez.
254
+
255
+ ### Profil, reklam rızası, reklam kimliği ve rozet
256
+
257
+ Yerel SDK'ların kalan yüzeyi de köprüde vardır; tek platforma özgü çağrılar diğer platformda zararsızdır (istisna yok,
258
+ etkisiz ya da `false`).
259
+
260
+ ```js
261
+ await Pushizo.login('user_42', { jwt, profile: { email: 'ali@ornek.com', sms: '+905551112233', tags: { plan: 'pro' }, aliases: { crm: 'c-1' } } });
262
+ await Pushizo.User.setAdsPersonalizationConsent(true); // reklam kişiselleştirme rızası; güncel tercihleri döndürür
263
+ const consents = await Pushizo.User.getConsents(); // [{ purpose, granted, source, updatedAt }]
264
+ await Pushizo.Ads.setAdvertisingId(gaidOrIdfa); // null kaydı siler
265
+ const shown = await Pushizo.Notifications.setBadgeCount(3); // rozet bu cihazda gösterilebiliyorsa true
266
+ await Pushizo.Notifications.clearBadge();
267
+ if (await Pushizo.Location.permissionGranted() && !(await Pushizo.Location.backgroundPermissionGranted())) {
268
+ await Pushizo.Location.requestBackgroundPermission('Mağazaya yaklaşınca haber vermek için'); // iOS: requestAlwaysPermission ile aynı
269
+ }
270
+ const listening = await Pushizo.Chat.isListening();
271
+ const ready = await Pushizo.isInitialized();
272
+ ```
273
+
274
+ | Metot | Açıklama |
275
+ |---|---|
276
+ | `login(externalId, { identityHash?, jwt?, profile? })` | `profile`: `{ email?, sms?, tags?, aliases? }`. Giriş ve profil tek çağrıda; geçersiz e-posta/telefon/takma ad girişten **önce** `INVALID_ARGUMENT` ile reddedilir. Doğrulama ve sıralama yerel SDK'lardadır (Android `login(id, HsUserProfile)`, iOS `login(_:profile:)`). |
277
+ | `User.setAdsPersonalizationConsent(granted)` | `Promise<UserPreferences>`: reklam kişiselleştirme rızası (`ads_personalization`); `false` rızayı geri alır. |
278
+ | `User.getConsents()` | `Promise<UserConsent[]>`: `purpose`, `granted`, `source`, `updatedAt` (epoch ms). Abonelik yoksa `NOT_READY`. |
279
+ | `User.registerAdm(token)` | Fire OS ADM kayıt kimliği (yalnızca Android; geçersiz kimlik `INVALID_ARGUMENT`). iOS: etkisiz. |
280
+ | `Ads.setAdvertisingId(id \| null)` | GAID/IDFA; `null` veya sıfır kimlik sunucudaki kaydı siler. Kimliği uygulama alır (SDK reklam kitaplığı ve ATT istemi içermez). |
281
+ | `Notifications.setBadgeCount(count)` / `clearBadge()` | `Promise<boolean>`: rozet bu cihazda gösterilebiliyorsa `true`. `count` negatif olmayan tam sayı (`RangeError`). iOS: uygulama rozeti ve bildirim uzantısıyla paylaşılan sayaç (her zaman `true`). Android: başlatıcı rozeti için "sayıyı ayarla" API'si olmadığından yerel SDK sayıyı saklar ve sonraki bildirimlere yazar; Android 8 öncesinde, bildirimler ya da kanal rozeti kapalıyken `false`. |
282
+ | `Notifications.getBadgeCount()` | `Promise<number>`: Android'de saklanan son sayı, iOS'ta uygulama simgesindeki rozet. |
283
+ | `Location.permissionGranted()` / `backgroundPermissionGranted()` | `Promise<boolean>`: ön plan / arka plan ("Her Zaman") konum izni; yerel SDK'dan okunur, istem açmaz. |
284
+ | `Location.requestBackgroundPermission(rationale?)` / `requestAlwaysPermission()` | `Promise<boolean>`: arka plan konum izni; iki ad aynı çağrıdır. Android: açıklama diyaloğu + `ACCESS_BACKGROUND_LOCATION` (Android 11+ Ayarlar ekranı; manifest'te yoksa `false`). iOS: "Her Zaman" izni (`rationale` kullanılmaz). |
285
+ | `Chat.isListening()` | `Promise<boolean>`: canlı dinleme açık mı. |
286
+ | `isInitialized()` | `Promise<boolean>`: yerel SDK başlatıldı mı. |
287
+
288
+ ### Kullanıcı özellikleri, gözlemciler, olay kimliği ve hazır sohbet ekranı
289
+
290
+ ```js
291
+ await Pushizo.User.setProperty('plan', 'pro'); // metin, sayı, mantıksal
292
+ await Pushizo.User.setProperty('address', { city: 'İzmir', tags: ['vip'] }); // dizi / düz nesne
293
+ await Pushizo.User.setProperty('plan', null); // null özelliği siler
294
+
295
+ const removeFlags = Pushizo.FeatureFlags.addObserver(async () => {
296
+ applyTheme(await Pushizo.FeatureFlags.getValue('tema', 'acik'));
297
+ });
298
+ const removeInbox = Pushizo.Inbox.addObserver(({ type, itemId, unreadCount }) => setBadge(unreadCount));
299
+
300
+ // Reklam pikseliyle aynı kimlik verilirse sunucu olayı tekilleşir.
301
+ await Pushizo.Session.sendEvent('purchase', { sku: 'A1' }, 49.9, { eventId: 'order_42:purchase' });
302
+
303
+ await Pushizo.Chat.show(); // hazır sohbet ekranı
304
+ if (await Pushizo.Chat.isPresented()) await Pushizo.Chat.hide();
305
+ ```
306
+
307
+ | Metot | Açıklama |
308
+ |---|---|
309
+ | `User.setProperty(key, value)` | Kullanıcı özelliği yazar; `null` siler. `key` 1-64 karakter (`TypeError` / `RangeError`); `value` metin, sonlu sayı, mantıksal ya da bunların dizisi/düz nesnesi (iç içe `null`, `Date`, fonksiyon vb. `TypeError`). Çevrimdışıyken yerel SDK kuyruğunda bekler. |
310
+ | `FeatureFlags.addObserver(cb)` / `removeObserver(cb)` | Bayrak değerleri sunucudan her yenilendiğinde (oturum başı ve `refresh()`) çağrılır; `addObserver` aboneliği kaldıran fonksiyonu döndürür. |
311
+ | `Inbox.addObserver(cb)` / `removeObserver(cb)` | Kutu değişim olayı: `{ type: 'listed' \| 'read' \| 'read_all' \| 'archived' \| 'count', itemId?, unreadCount }`. `read`/`read_all`/`archived` her işlemde, `listed`/`count` yalnızca okunmamış sayısı değiştiğinde bildirilir; `itemId` yalnızca tek öğe olaylarında bulunur. |
312
+ | `Session.sendEvent(name, properties?, value?, { eventId? })` | `eventId` tekilleştirme kimliğidir: 8-64 karakter; harf, rakam ve `. _ : -`. Biçim geçersizse yerel SDK kendi kimliğini üretir; metin olmayan kimlik `TypeError`. |
313
+ | `Chat.show()` / `hide()` | Hazır sohbet ekranını açar / kapatır (Android `HsChatActivity`, iOS modal `HSChatViewController`). Ekran açıksa yenisi açılmaz; `initialize` öncesinde `show()` `NOT_READY` ile reddedilir. |
314
+ | `Chat.isPresented()` | `Promise<boolean>`: hazır sohbet ekranı açık mı. Yerel Android SDK bu durumu dışa açmadığından köprü `HsChatActivity` yaşam döngüsünü izler. |
315
+
316
+ Köprüye bağlanamayan yerel yüzey: yerel görünümler (`HsChatView`, `HsContentCardsView`, iOS `HSChatViewController` gömme) ve
317
+ `InAppMessages.setRenderer` (özel çizici yerel kod ister).
318
+
319
+ ### Gömülü yerleşimler
320
+
321
+ Uygulamanın ayırdığı bir alana (ana sayfa afişi, liste arası kart) dashboard'dan içerik gönderin
322
+ ([ADR-0068](https://github.com/pushizo/pushizo/blob/main/docs/adr/0068-gomulu-yerlesimler.md)). Köprü yalnızca modeli
323
+ döndürür; çizim uygulamanındır.
324
+
325
+ ```js
326
+ const messages = await Pushizo.Placements.list('home_banner', { limit: 2 }); // InAppMessage[]
327
+ for (const message of messages) {
328
+ render(message.display.blocks); // title/body/image/button/carousel blokları veya display.html
329
+ await Pushizo.Placements.reportImpression(message); // içerik ekrana gelince
330
+ }
331
+ await Pushizo.Placements.reportClick(message, buttonId); // düğme tıklanınca (buttonId: blok/kart düğmesinin id'si)
332
+ await Pushizo.Placements.reportDismiss(message); // kullanıcı kapatınca
333
+ ```
334
+
335
+ - Anahtar `^[a-z][a-z0-9_.-]{0,63}$` kalıbına uymalı, `limit` 1-10 olmalıdır; aksi halde çağrı köprüye gitmeden
336
+ `TypeError`/`RangeError` ile reddedilir. Abonelik yoksa veya gizlilik onayı bekleniyorsa liste boştur.
337
+ - `InAppMessage` alanları yerel modelle aynıdır (`id`, `priority`, `triggers`, `triggerGroups`, `variantId`, `display`,
338
+ `remainingImpressions`, `minIntervalSeconds`, `stopAfterInteraction`, `lastImpressionAt`, `endAt`, `language`); zamanlar
339
+ epoch milisaniyedir. Düğme aksiyonları (`url`, `deeplink`, `tags`, `push_prompt`, `outcome`, `dismiss`) uygulama
340
+ tarafından yürütülür.
341
+ - Rapor çağrıları yerel tarafta son `list` yanıtlarındaki mesajı kimliğiyle bulur (en çok 50 mesaj saklanır); listeden
342
+ gelmeyen bir mesaj için rapor sessizce yok sayılır (debug log).
343
+ - Ağ/sunucu hatasında Android boş liste döndürür; iOS çağrıyı hata koduyla reddeder.
344
+
345
+ ### Olaylar
346
+
347
+ ```js
348
+ Pushizo.Notifications.addForegroundLifecycleListener((event) => {
349
+ event.preventDefault(); // ön planda gösterme; sonra göstermek için: event.display()
350
+ });
351
+ Pushizo.Notifications.addPermissionObserver(({ permission }) => {});
352
+ Pushizo.User.pushSubscription.addObserver((state) => {}); // { id, token, optedIn, permission }
353
+ Pushizo.InAppMessages.addClickListener((e) => {}); // { message: { id }, result: { actionId, url } }
354
+ Pushizo.InAppMessages.addLifecycleListener({ willDisplay() {}, didDismiss() {} });
355
+ ```
356
+
357
+ `addPermissionObserver` olayları yerel Android/iOS SDK izin gözlemcisinden gelir (izin isteği sonucu ve uygulama ön plana
358
+ döndüğünde ayarlardan yapılan değişiklik; yalnızca gerçek değişiklikte).
359
+
360
+ Her `add…` çağrısı aboneliği kaldıran bir fonksiyon döndürür. Olaylar native taraftan tek bir `keepCallback` kanalıyla gelir; kanal açılmadan oluşan olaylar (ör. soğuk başlatma tıklaması) native tarafta tamponlanır.
361
+
362
+ ### In-app, bildirim kutusu ve diğerleri
363
+
364
+ ```js
365
+ await Pushizo.InAppMessages.addTrigger('level', 5);
366
+ await Pushizo.InAppMessages.setScreen('checkout');
367
+ await Pushizo.InAppMessages.setPaused(false);
368
+
369
+ const page = await Pushizo.Inbox.list({ limit: 20 }); // { items, unreadCount, nextCursor, hasMore }
370
+ await Pushizo.Inbox.markRead(page.items[0].id);
371
+ await Pushizo.Inbox.markAllRead();
372
+ await Pushizo.Inbox.archive(page.items[0].id);
373
+
374
+ // Tercihler (kategori × kanal opt-in; channel verilmezse tüm kanallar). Abonelik yoksa NOT_READY.
375
+ const { preferences, categories } = await Pushizo.User.getPreferences();
376
+ await Pushizo.User.setPreferences([
377
+ { category: 'promo', optedIn: false },
378
+ { category: 'news', channel: 'email', optedIn: true },
379
+ ]); // güncel listeyi döndürür
380
+
381
+ await Pushizo.Notifications.clearAll();
382
+ await Pushizo.Notifications.removeGroupedNotifications('orders');
383
+ await Pushizo.Notifications.removeNotification(id); // Android: notification.androidNotificationId; iOS: UNNotificationRequest.identifier (metin)
384
+ await Pushizo.setConsentGiven(true); // requiresPrivacyConsent: true ile başlatıldıysa
385
+ await Pushizo.Debug.setLogLevel('debug');
386
+ await Pushizo.logout();
387
+ ```
388
+
389
+ ### HTML in-app ve carousel
390
+
391
+ In-app mesajları yerel Android/iOS SDK'sı çizer; bu paket köprüdür. HTML in-app (sandbox'lı WebView, köprü
392
+ `close`/`click`/`addTag`/`trackEvent`) ve carousel blokları yerel SDK'dan olduğu gibi devralınır: ek kod veya
393
+ yapılandırma gerekmez, tıklama ve yaşam döngüsü olayları mevcut in-app dinleyicilerine gelir. Yetenek bildirimi
394
+ (`supports=html,carousel`) yerel SDK tarafından yapılır; desteklemeyen eski yerel sürümlere sunucu HTML mesaj göndermez
395
+ ve carousel bloklarını çıkarır.
396
+
397
+ ## Android kurulumu (FCM)
398
+
399
+ 1. Firebase konsolunda Android uygulaması ekleyin; `google-services.json` dosyasını proje köküne koyun ve `config.xml` içine ekleyin:
400
+
401
+ ```xml
402
+ <platform name="android">
403
+ <preference name="GradlePluginKotlinEnabled" value="true" />
404
+ <preference name="GradlePluginGoogleServicesEnabled" value="true" />
405
+ <preference name="GradlePluginGoogleServicesVersion" value="4.4.2" />
406
+ <preference name="android-compileSdkVersion" value="35" />
407
+ <resource-file src="google-services.json" target="app/google-services.json" />
408
+ </platform>
409
+ ```
410
+
411
+ Köprü Kotlin ile yazıldığından `GradlePluginKotlinEnabled` zorunludur. Yerel SDK 0.3.0'in `androidx.work` bağımlılığı
412
+ `compileSdk` 35 ister; cordova-android 13'ün varsayılanı 34 olduğundan `android-compileSdkVersion` tercihi gerekir.
413
+ 2. Pushizo dashboard'unda Firebase servis hesabı JSON'unu yükleyin (kurulum sihirbazında **Cordova** seçilebilir); kayıt sonrası otomatik doğrulanır.
414
+ 3. Eklenti `com.pushizo:pushizo-android:0.3.0` artefaktına bağlıdır (özellik bayrakları, yerleşimler ve bölge izleme bu sürümle gelir). Maven Central yayınına kadar `sdk/android` içinde `gradle :pushizo:publishToMavenLocal` çalıştırın; eklenti `mavenLocal()` deposunu ekler.
415
+ 4. FCM servisi, `POST_NOTIFICATIONS` izni ve bildirim Activity'si SDK manifestinden birleşir. Bildirim ikonu için `AndroidManifest.xml` içinde `com.pushizo.sdk.default_notification_icon` meta-data'sı verilebilir.
416
+
417
+ Eklenti, JS ile yapılan `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.
418
+
419
+ ## iOS kurulumu (APNs)
420
+
421
+ 1. `config.xml`:
422
+
423
+ ```xml
424
+ <platform name="ios">
425
+ <preference name="deployment-target" value="15.0" />
426
+ <preference name="SwiftVersion" value="5" />
427
+ </platform>
428
+ ```
429
+
430
+ 2. Eklenti Push Notifications yetkisini (`aps-environment`) ve `remote-notification` arka plan modunu ekler. Pushizo dashboard'unda APNs `.p8` anahtarını veya `.p12` sertifikasını yükleyin.
431
+ 3. `Pushizo` pod'u yayınlanana kadar `platforms/ios/Podfile` içinde `pod 'Pushizo', :path => '<repo>/sdk/ios'` kullanın ve `pod install` çalıştırın.
432
+ 4. APNs token geri çağrıları (`didRegisterForRemoteNotificationsWithDeviceToken`/`didFailToRegister…`) eklenti yüklenirken AppDelegate sınıfına çalışma zamanında eklenir; AppDelegate'te bu metotlar varsa önce SDK'ya iletilir, sonra sizin kodunuz çalışır.
433
+ 5. Pushizo SDK'sı `UNUserNotificationCenter` delegesini üstlenir; başka bir push eklentisiyle (ör. `cordova-plugin-firebasex`) birlikte kullanmayın.
434
+
435
+ ### Notification Service Extension (zengin medya, teslim bildirimi)
436
+
437
+ Resimli bildirimler, rozet artışı ve uygulama kapalıyken `received` bildirimi için Xcode'da (`platforms/ios/*.xcworkspace`) **File → New → Target → Notification Service Extension** ekleyin (iOS 15), Podfile'a hedefi ekleyin:
438
+
439
+ ```ruby
440
+ target 'PushizoNSE' do
441
+ pod 'Pushizo/Extension', :path => '<repo>/sdk/ios'
442
+ end
443
+ ```
444
+
445
+ ve `NotificationService.swift` dosyasını SDK yardımcısına devredin:
446
+
447
+ ```swift
448
+ import UserNotifications
449
+ import Pushizo
450
+
451
+ class NotificationService: UNNotificationServiceExtension {
452
+ let hs = PushizoNotificationServiceExtension(appId: "app_xxx", apiUrl: "https://api.pushizo.com",
453
+ appGroup: "group.com.pushizo.app.pushizo")
454
+
455
+ override func didReceive(_ request: UNNotificationRequest, withContentHandler handler: @escaping (UNNotificationContent) -> Void) {
456
+ hs.didReceive(request, withContentHandler: handler)
457
+ }
458
+
459
+ override func serviceExtensionTimeWillExpire() { hs.serviceExtensionTimeWillExpire() }
460
+ }
461
+ ```
462
+
463
+ Uygulama ve NSE hedeflerinde aynı App Group yeteneğini açın ve uygulamanın `Info.plist` dosyasına `PushizoAppGroup` anahtarıyla yazın (rozet sayacı paylaşımı). `cordova platform rm/add ios` Xcode projesini yeniden oluşturduğundan NSE hedefi yeniden eklenmelidir.
464
+
465
+ ## Geliştirme
466
+
467
+ ```bash
468
+ npm install
469
+ npm run typecheck
470
+ npm test # vitest: cephe, cordova.exec köprüsü ve native sözleşme denetimi
471
+ npm run build # src/*.ts → www/*.js (eklentiyle birlikte yayınlanır, depoda tutulur)
472
+ ```
473
+
474
+ Adım adım kurulum ve örnek kod: [cordova rehberi](https://docs.pushizo.com/docs/sdk/cordova).
475
+
476
+ <!-- pushizo:footer -->
477
+ ---
478
+
479
+ ## Support · Destek
480
+
481
+ - **Guide · Rehber:** [docs.pushizo.com/docs/sdk/cordova](https://docs.pushizo.com/docs/sdk/cordova)
482
+ - **API reference & OpenAPI · API referansı ve OpenAPI:** [docs.pushizo.com/docs/api](https://docs.pushizo.com/docs/api) ·
483
+ [pushizo-openapi](https://github.com/pushizo/pushizo-openapi)
484
+ - **Bugs & ideas · Hata ve öneri:** [Issues](https://github.com/pushizo/pushizo-cordova/issues)
485
+ - **Security · Güvenlik:** please do not open public issues; email [security@pushizo.com](mailto:security@pushizo.com) ·
486
+ herkese açık issue açmayın, bu adrese yazın.
487
+ - **Help · Destek:** [support@pushizo.com](mailto:support@pushizo.com)
488
+
489
+ This repository is mirrored automatically from the Pushizo main repository on every release. Please open an issue
490
+ instead of a pull request; fixes land in the main repository and ship with the next release.
491
+ Bu depo her sürümde Pushizo ana deposundan otomatik yansıtılır. Pull request yerine issue açın; düzeltmeler ana depoda
492
+ yapılır ve bir sonraki sürümle buraya gelir.
493
+
494
+ Released under the MIT License · MIT lisanslıdır — [LICENSE](https://github.com/pushizo/pushizo-cordova/blob/main/LICENSE).
495
+ <!-- /pushizo:footer -->