Unity SDK
com.pushizo.unity — Android ve iOS yerel SDK'larını saran UPM paketi (Unity 2021.3+); push, in-app, bildirim kutusu, tercihler, otomatik iOS/Android derleme ayarları.
com.pushizo.unity, yerel Pushizo Android (com.pushizo:pushizo-android) ve iOS (Pushizo Swift) SDK'larını sarar; tetik değerlendirme, çevrimdışı kuyruk, teslimat geri bildirimi ve in-app çizimi yerel SDK'dadır. Yüzey OneSignal v5 ile, Flutter ve .NET MAUI SDK'larıyla aynıdır. Ad alanı PushizoSdk. Örnek: paket içi Demo örneği (Samples~/Demo).
| Platform | Davranış |
|---|---|
| Android cihaz (minSdk 23) | Yerel Android SDK'sı; Java köprüsü Runtime/Plugins/Android |
| iOS cihaz (iOS 15+) | Yerel iOS SDK'sı; Swift köprüsü Runtime/Plugins/iOS ([DllImport("__Internal")]) |
| Unity Editor, Standalone, WebGL | Ağ çağrısı ve push yok; çağrılar günlüğe yazılır, tag/tetik/e-posta bellekte tutulur, bildirim kutusu ve tercihler PLATFORM_NOT_SUPPORTED (Pushizo.IsSupported false) |
Gereksinimler: Unity 2021.3+, External Dependency Manager for Unity (EDM4U) (Android Gradle ve iOS CocoaPods bağımlılıkları), iOS için CocoaPods.
Kurulum
Packages/manifest.json (ya da Window → Package Manager → + → Add package from git URL):
{
"dependencies": {
"com.pushizo.unity": "https://github.com/exec0de/pushizo.git?path=sdk/unity#sdk-v0.1.0"
}
}Project Settings → Pushizo: App ID, API URL (iOS Notification Service Extension için), APNs ortamı (development/production), App Group, NSE hedefi açık/kapalı ve google-services.json yolu. Ayarlar Assets/Pushizo/PushizoSettings.asset dosyasına yazılır ve derleme sonrası işlemlerde kullanılır; çalışma zamanında SDK yine Pushizo.Initialize ile başlatılır.
Android
- Firebase konsolundan
google-services.jsonindiripAssets/google-services.jsonyoluna koyun. Derleme sırasında Firebase değerleri (google_app_id,gcm_defaultSenderId,google_api_key,project_id) unityLibrary kaynaklarına yazılır; Firebase Unity SDK'sı gerekmez. - Dashboard → Kanallar → Android Push → Firebase servis hesabı JSON'u.
- Player Settings → Minimum API Level 23.
POST_NOTIFICATIONSizni ve FCM servisi yerel SDK manifestinden birleşir. - Gradle bağımlılıkları EDM4U ile çözülür (
Editor/PushizoDependencies.xml: yerel SDK, Kotlin stdlib, AndroidX Core). Yerel SDK Maven Central'a yayımlanana kadargradle -p sdk/android :pushizo:publishToMavenLocalçalıştırıp Player Settings → Publishing Settings → Custom Main Gradle / Settings Template'temavenLocal()deposunu ekleyin.
iOS
Derleme sonrası işlem (Editor/PushizoIosPostProcessor.cs) otomatik olarak şunları ekler:
- Push Notifications yeteneği (
aps-environment) ve Background Modes → Remote notifications, - isteğe bağlı App Group,
- Swift köprüsü için derleme ayarları (
SWIFT_VERSION, Swift çalışma zamanı gömme), Classes/Preprocessor.h→UNITY_USES_REMOTE_NOTIFICATIONS 1(Unity bu değeri yalnız kendi bildirim API'leri kullanıldığında açar; kapalıykenUnityAppControllerAPNs token'ını almaz ve köprüye iletmez),- PushizoNotificationServiceExtension hedefi (zengin medya, rozet, teslimat onayı) ve Podfile'a
Pushizo/Extensionpod'u (EDM4U Podfile'ı 40'ta üretir, eklenti 45'te çalışır,pod install50'de).
APNs token'ı Unity'nin UnityAppController bildirimlerinden alınır; AppDelegate değişikliği gerekmez. Xcode'da imzalama ekibini her iki hedef için seçin (Player Settings → iOS → Signing Team ID verildiyse otomatik). Dashboard → Kanallar → iOS Push → .p8 anahtarı. Yerel SDK CocoaPods'a yayımlanana kadar oluşan Podfile'da pod 'Pushizo/App', :path => '<repo>/sdk/ios' (NSE hedefinde Pushizo/Extension). NSE ayrıntısı: iOS SDK.
Başlatma
using System.Collections.Generic;
using PushizoSdk;
using UnityEngine;
public class PushizoBootstrap : MonoBehaviour
{
private void Awake()
{
Pushizo.Initialize("app_…", new PushizoOptions
{
ApiUrl = "https://api.example.com",
RequiresPrivacyConsent = false, // true ise SetConsentGiven(true) gelene kadar ağ çağrısı yok
LogLevel = LogLevel.Warn,
// Android: AndroidDefaultChannelId, AndroidDefaultChannelName · iOS: IosAppGroup, IosApnsEnvironment, IosProvisionalAuthorization
});
Pushizo.Notifications.Clicked += e => Debug.Log($"Tıklandı: {e.Url}");
}
}Initialize ana iş parçacığından, uygulama açılışında bir kez çağrılır; aynı App ID ile tekrar çağrı etkisizdir, farklı App ID InvalidOperationException üretir. Tüm olaylar ve Task sonuçları Unity ana iş parçacığında teslim edilir (gizli PushizoDispatcher nesnesi).
İzin
bool granted = await Pushizo.Notifications.RequestPermissionAsync(fallbackToSettings: true); // kalıcı redde ayarları açar
bool current = Pushizo.Notifications.Permission;
Pushizo.Notifications.PermissionChanged += granted => Debug.Log(granted); // yerel izin gözlemcisinden, yalnızca gerçek değişiklikteKullanıcı, abonelik, tag ve alias
Pushizo.SetConsentGiven(true); // false: kuyruk ve yerel kimlik temizlenir
Pushizo.Login("user_42", identityHash); // identity verification açıksa hash zorunlu
Pushizo.Logout();
Pushizo.User.AddTag("level", "12");
Pushizo.User.AddTags(new Dictionary<string, string> { ["level"] = "12", ["clan"] = "red" });
Pushizo.User.RemoveTag("level"); // RemoveTags(new[] { "level", "clan" })
var tags = Pushizo.User.GetTags();
Pushizo.User.SetLanguage("tr");
Pushizo.User.AddAlias("crm_id", "42"); // AddAliases(dict), RemoveAlias("crm_id")
string? externalId = Pushizo.User.ExternalId; string? hsId = Pushizo.User.Id;
var sub = Pushizo.User.PushSubscription; // Id, Token, OptedIn, Current
sub.OptIn(); sub.OptOut();
sub.Changed += e => Debug.Log($"{e.Previous.Id} → {e.Current.Id}");E-posta ve SMS
Pushizo.User.AddEmail("ali@example.com"); // geçersizse ArgumentException
Pushizo.User.RemoveEmail("ali@example.com");
Pushizo.User.AddSms("+905321234567"); // E.164 bekler
Pushizo.User.RemoveSms("+905321234567");
var emails = Pushizo.User.Emails; // SmsNumbersKullanıcı tercihleri
UserPreferences prefs = await Pushizo.User.GetPreferencesAsync(); // prefs.Preferences, prefs.Categories
foreach (var category in prefs.Categories) Debug.Log(category.LocalizedName("tr"));
await Pushizo.User.SetPreferencesAsync(new[]
{
new PreferenceInput("promo", optedIn: false), // channel null = tüm kanallar
new PreferenceInput("news", optedIn: true, channel: "email"), // ios_push | android_push | web_push | email | sms
});SetPreferencesAsync girdiyi köprüden önce doğrular (1-100 kayıt, kategori 1-64 karakter, bilinen kanal ya da null); geçersizse ArgumentException. Abonelik henüz yoksa PushizoException (NOT_READY); Editor'de PLATFORM_NOT_SUPPORTED. Kategori modeli: Tercihler.
Bildirim olayları
Pushizo.Notifications.Clicked += e => OpenScreen(e.Url); // e.Notification, e.ActionId, e.Url
Pushizo.Notifications.ForegroundWillDisplay += e =>
{
if (inBattle) e.PreventDefault(); // gerekirse daha sonra e.Display()
};Uygulama bildirimle açıldığında henüz Clicked abonesi yoksa son tıklama saklanır ve ilk aboneye iletilir. ForegroundWillDisplay abonesi varken yerel gösterim ertelenir; işleyiciler PreventDefault() çağırmazsa bildirim gösterilir (iOS'ta karar 25 sn içinde verilmelidir). PushizoNotification: Title, Body, ImageUrl, Url, DeliveryId, MessageId, Actions, Data.
In-app mesajlar
Pushizo.InAppMessages.AddTrigger("level", "gold"); // AddTriggers(dict), RemoveTrigger(s), ClearTriggers(), GetTriggers()
Pushizo.InAppMessages.SetScreen("shop"); // sahneden çıkarken SetScreen(null)
Pushizo.InAppMessages.Paused = true; // ara sahnede/oyun içinde gösterme
Pushizo.InAppMessages.Clicked += e => Debug.Log($"{e.MessageId} {e.ActionId} {e.Url}");
Pushizo.InAppMessages.DidDisplay += e => Debug.Log(e.Message.Id); // WillDisplay, WillDismiss, DidDismissMesajlar yerel arayüzle (Android Dialog, iOS UIWindow) Unity görünümünün üstünde çizilir.
Bildirim kutusu
InboxPage page = await Pushizo.Inbox.ListAsync(limit: 20, cursor: null); // Items, UnreadCount, NextCursor, HasMore
InboxItem item = await Pushizo.Inbox.MarkReadAsync(page.Items[0].Id);
int remaining = await Pushizo.Inbox.MarkAllReadAsync();
await Pushizo.Inbox.ArchiveAsync(item.Id);
int unread = await Pushizo.Inbox.UnreadCountAsync();Olaylar (outcome) ve diğerleri
Pushizo.Session.SendEvent("purchase", new Dictionary<string, object> { ["sku"] = "gems_100" }, value: 4.99);
Pushizo.Notifications.ClearAll(); // bu uygulamanın bildirimleri (iOS'ta rozet de sıfırlanır)
Pushizo.Notifications.RemoveGroupedNotifications("orders"); // Android android_group / iOS thread-id
Pushizo.Notifications.RemoveNotification(n.AndroidNotificationId!.Value); // Android tepsi kimliği (iOS'ta null)
Pushizo.Notifications.RemoveNotification("istek-kimligi"); // iOS: UNNotificationRequest.identifier
Pushizo.Debug.SetLogLevel(LogLevel.Debug); // None | Error | Warn | Info | DebugPushizo.Debug SDK yöneticisidir; UnityEngine.Debug ile karışmaması için gerekirse tam adını kullanın.
Hata kodları
Bildirim kutusu ve tercih hataları PushizoException.Code taşır:
| Kod | Anlam |
|---|---|
NOT_READY | Abonelik/kullanıcı kaydı henüz tamamlanmadı. |
INVALID_ARGUMENT | Yerel SDK girdiyi reddetti. |
PLATFORM_NOT_SUPPORTED | Editor, Standalone veya WebGL. |
INVALID_RESPONSE | Köprü yanıtı ayrıştırılamadı. |
HS_… | Sunucu hata kodu; katalog: Hatalar. |
C# tarafındaki doğrulama hataları (ArgumentException) köprüye gitmeden fırlatılır; Initialize'dan önce yapılan çağrılar InvalidOperationException.
Test ve örnek
# Editörsüz çekirdek (yönetilen katman)
cd sdk/unity/Validation~ && dotnet test Pushizo.Unity.Validation.sln
# Gerçek Unity Editor (EditMode testleri + Windows/Android/iOS hedef derlemeleri)
powershell -ExecutionPolicy Bypass -File sdk/unity/TestProject~/run-tests.ps1Kendi projenizde EditMode testleri için Packages/manifest.json → "testables": ["com.pushizo.unity"] ve Window → General → Test Runner. Örnek: Package Manager → Pushizo → Samples → Demo → Import; boş bir sahnede bir GameObject'e PushizoDemo bileşenini ekleyip App ID ve API adresini girin.
Sorun giderme
| Belirti | Neden / çözüm |
|---|---|
| Editor'de push gelmiyor | Beklenen davranış: Editor/Standalone/WebGL'de yerel SDK yoktur; cihazda deneyin. |
Android: google_app_id eksik / token yok | google-services.json Project Settings → Pushizo'daki yolda değil. |
Android: pushizo-android çözümlenemiyor | EDM4U kurulu değil, Force Resolve yapılmadı ya da mavenLocal() eklenmedi. |
iOS: Pushizo modülü bulunamadı | EDM4U pod install çalışmadı; Xcode'da .xcodeproj yerine .xcworkspace'i açın. |
| iOS: NSE imzalama hatası | NSE hedefi için de imzalama ekibini seçin (ya da Signing Team ID verin). |
RequestPermissionAsync hep false | Android 13+'ta izin reddedildi (fallbackToSettings: true); iOS'ta Push yeteneği eksik. Diğer belirtiler: Android, iOS. |
.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.
Node.js SDK
@pushizo/node — Node.js ≥ 20, ESM, OpenAPI'den türetilmiş tipler; bildirim, kullanıcı, olay, webhook imza doğrulama, journey ve tüm public API.