NotiPilot Device API — Geliştirici Dokümanı

API sürümü: 1.0.0 · Base path: /api/v1

NotiPilot, mobil uygulamanızdaki cihazları kaydedip segmentlere ayırmanızı ve NotiPilot paneli üzerinden bu cihazlara push bildirim göndermenizi sağlar. Mobil uygulamanız yalnızca iki endpoint ile konuşur:

Bildirim gönderimi NotiPilot panelinden yapılır; mobil uygulamanın gönderim yapmasına gerek yoktur.

#Platform rehberleri

Sürüm desteği ve versiyonlama politikası

#1. Nasıl çalışır?

Mobil uygulama ──(Expo Push Token + cihaz bilgileri)──▶ NotiPilot API
                                                              │
NotiPilot paneli ──(başlık, mesaj, segment)──▶ Expo Push Service ──▶ FCM (Android) / APNs (iOS) ──▶ Cihaz

NotiPilot 1.0.0, teslimat için Expo Push Service kullanır. Bu nedenle:

• Her cihazın bir Expo Push Token'ı (ExponentPushToken[...]) olmalıdır. Expo ve React Native uygulamalarında bu token doğrudan expo-notifications ile alınır. Native Android/iOS uygulamalarda cihazın FCM/APNs token'ı Expo token'ına dönüştürülür (ilgili rehberlerde adım adım anlatılmıştır).
• Uygulamanızın bir Expo (EAS) projesi olmalı ve FCM V1 / APNs kimlik bilgileri bu projeye yüklenmiş olmalıdır (eas credentials).
• NotiPilot paneline uygulamanızı eklerken Expo Project ID ve Expo Access Token bilgilerini girersiniz.

API'ye doğrudan FCM veya APNs token'ı da gönderebilirsiniz (provider: "fcm" | "apns"). Bu cihazlar kaydedilir ve segmentlerde görünür, ancak 1.0.0 sürümünde bildirim yalnızca Expo token'ı olan cihazlara teslim edilir. Doğrudan FCM/APNs teslimatı yol haritasındadır.

#2. Başlamadan önce

1. NotiPilot panelinde Uygulama Ekle ekranından uygulamanızı oluşturun.
2. Expo Project ID alanına EAS proje ID'nizi (UUID, app.json → extra.eas.projectId) girin.
3. Expo Access Token alanına expo.dev → Access Tokens sayfasından oluşturduğunuz token'ı girin. (Expo projenizde "Enhanced Security for Push Notifications" açıksa zorunludur.)
4. Mobil uygulamada API'ye gönderdiğiniz app_id, panelde girdiğiniz Expo Project ID ile birebir aynı olmalıdır. Kayıtlı olmayan bir app_id gönderilirse API 404 unknown_app döner.

#3. Genel kurallar

Geriye dönük uyumluluk için /api/register-device ve /api/identify-device (sürümsüz) adresleri de v1 ile aynı şekilde çalışır. Yeni entegrasyonlarda /api/v1 kullanın.

#4. Endpoint'ler

#4.1 POST /api/v1/register-device

Cihazı kaydeder veya günceller (upsert). Eşleştirme anahtarı app_id + device_uid ikilisidir; aynı cihaz için tekrar tekrar çağırmak güvenlidir.

İstek alanları

Örnek istek

curl -X POST "https://app.notipilot.com/api/v1/register-device" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1c2d3e4f-5a6b-7c8d-9e0f-112233445566",
    "device_uid": "8f14e45f-ceea-467a-9575-0b3f5c6b2a11",
    "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
    "platform": "android",
    "attributes": {
      "locale": "tr",
      "country": "TR",
      "city": "Istanbul",
      "app_version": "2.4.0"
    },
    "tags": ["beta"]
  }'

Başarılı yanıt — 200 OK

{
  "success": true,
  "message": "Device registered successfully",
  "device_id": 1234,
  "expo_token_id": 567,
  "provider": "expo"
}

#4.2 POST /api/v1/identify-device

Cihazı kendi kullanıcı ID'nizle (external_id) eşleştirir ve isteğe bağlı olarak attributes/tags günceller. Kullanıcı giriş yaptığında çağırın.

curl -X POST "https://app.notipilot.com/api/v1/identify-device" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1c2d3e4f-5a6b-7c8d-9e0f-112233445566",
    "device_uid": "8f14e45f-ceea-467a-9575-0b3f5c6b2a11",
    "external_id": "user_98765",
    "attributes": { "gender": "female" }
  }'

{ "success": true, "message": "Device identified", "device_id": 1234 }

Cihaz henüz kayıtlı değilse ve token gönderilmediyse cihaz token'sız olarak oluşturulur ("auto_registered": true). Bu cihaza, register-device ile token gönderilene kadar bildirim gitmez.

#4.3 GET /api/v1/version

Sağlık kontrolü ve sürüm bilgisi.

{ "success": true, "api_version": "1.0.0", "min_supported_version": "1.0.0" }

#5. Attributes ve segmentler

NotiPilot paneli, cihazların attributes değerlerinden otomatik segment üretir (ör. "Türkçe konuşanlar", "İstanbul", "Türkiye + İstanbul"). Konum bazlı segmentler yalnızca country ve city gönderen cihazlar için oluşur. Bu alanları göndermezseniz cihaz yalnızca "Tüm kullanıcılar" gönderimlerine dahil olur.

Standart anahtarlar (panel bunları tanır ve etiketler):

Kendi anahtarlarınızı da ekleyebilirsiniz (app_version, plan, favorite_team …).

Kurallar

• En fazla 50 anahtar. Anahtarlar A-Z a-z 0-9 _ . - karakterlerinden oluşur, en fazla 64 karakter.
• Değerler string, sayı, boolean veya null olabilir. String değerler en fazla 255 karakter.
• Değerlerde , ve : karakterlerini kullanmayın (segment anahtarlarında ayırıcı olarak kullanılır).
• Birleştirme (merge): Gönderdiğiniz attributes mevcut değerlerle birleştirilir; göndermediğiniz anahtarlar korunur. Bir anahtarı silmek için değerini null gönderin.
• attributes alanını hiç göndermezseniz kayıtlı attributes değişmez.
• E-posta, telefon, T.C. kimlik no gibi kişisel verileri attributes'a koymayın. Kullanıcıyı eşleştirmek için external_id kullanın.

Şehir/ülke bilgisini nereden almalı? Cihazın bölge ayarı (locale → ülke) konum izni gerektirmez ve her zaman kullanılabilir. Şehir için; kullanıcının profilindeki şehir (en güvenilir yöntem), konum izni verdiyse reverse-geocoding, ya da kendi backend'inizde IP tabanlı konum tespiti kullanılabilir. Konum izni verilmediğinde de en azından country ve locale göndermeniz önerilir.

#6. Cihaz kimliği nasıl üretilmeli?

device_uid alanı için:

• Uygulama ilk açıldığında bir UUID v4 üretin ve kalıcı olarak saklayın (Android: SharedPreferences/DataStore, iOS: Keychain, Expo: expo-secure-store).
• Uygulama güncellemelerinde değişmemeli; uygulama silinip yeniden kurulduğunda değişmesi normaldir.
• IMEI, MAC adresi veya reklam kimliği (IDFA/GAID) kullanmayın.

#7. Hata yanıtları

Tüm hata yanıtları aynı yapıdadır:

{
  "success": false,
  "error": "validation_failed",
  "message": "Validation failed",
  "errors": { "platform": "Must be one of: android, ios, web" }
}

İstemci tarafında önerilen yaklaşım: yalnızca 429 ve 5xx durumlarında (ve ağ hatalarında) yeniden deneyin; 4xx hatalarını loglayın.

#8. Önerilen akış

1. Uygulama açılır → device_uid okunur (yoksa üretilir).
2. Bildirim izni istenir (Android 13+ ve iOS'ta zorunlu).
3. İzin verildiyse push token alınır → register-device çağrılır (locale/country/city ile birlikte).
4. Kullanıcı giriş yapar → identify-device çağrılır (external_id ile).
5. Kullanıcı çıkış yapar → register-device, "external_id": null ile çağrılır.
6. Push token yenilenirse (onNewToken / token listener) → register-device tekrar çağrılır.

#9. Bildirim içeriği

Panelden gönderilen bildirim title, body ve isteğe bağlı JSON data alanlarından oluşur. data içeriği uygulamanıza iletilir; derin bağlantı (deep link) gibi senaryolar için kullanın, örneğin:

{ "screen": "product", "product_id": "12345" }

Android'de bildirimler default kanalına (channelId: "default") gönderilir; uygulamanızda bu ID ile bir bildirim kanalı oluşturun.

#10. Değişiklik günlüğü