Skip to main content
Bu kılavuz, Android Studio kullanarak Android uygulamanıza OneSignal ekleme sürecinde size yol gösterir. SDK’mızı yükleyecek, push ve uygulama içi mesajları ayarlayacak ve her şeyin çalıştığını doğrulamak için test mesajları göndereceksiniz. OneSignal’ı ilk kez kullanıyorsanız adımları sırasıyla takip edin. Deneyimliyseniz ihtiyacınız olan bölümlere doğrudan geçebilirsiniz.
Yapay zeka kodlama asistanı mı kullanıyorsunuz? Yapay zeka destekli kurulum için şu istemi kullanın:

Adım 0. OneSignal’da FCM yapılandırması (push göndermek için gerekli)

Bu adımı tamamlamadan OneSignal Android SDK’sını yükleyip başlatabilirsiniz. Ancak Firebase Cloud Messaging (FCM) kimlik bilgileri OneSignal uygulamanızda yapılandırılana kadar push bildirimleri teslim edilmeyecektir.
Şirketinizin zaten bir OneSignal hesabı varsa, uygulamayı yapılandırmak için yönetici rolüyle davet edilmeyi isteyin. Aksi takdirde, başlamak için ücretsiz bir hesap oluşturun.
Bu adımlar OneSignal uygulamanızı Firebase Cloud Messaging (FCM) ile bağlar. Bunu uygulama başına yalnızca bir kez yapmanız gerekir.
  1. https://onesignal.com adresine giriş yapın ve Uygulamanızı oluşturun veya seçin.
  2. Settings > Push & In-App bölümüne gidin.
  3. Google Android (FCM) seçeneğini seçin ve kurulum sihirbazında Continue ile devam edin.
  4. FCM Service Account JSON dosyanızı yükleyin.
  5. App ID’nizi almak için kurulum sihirbazında devam edin. Bu, SDK’yı başlatmak için kullanılacaktır.
Tam kurulum talimatları için Mobil push kurulumu kılavuzumuza bakın.

Kurulum sözleşmesi ve gereksinimler

Bu bölüm, kılavuz boyunca kullanılan araçları, sürümleri ve varsayımları özetler.
  • SDK sürümü: 5.6.1+ (en son: sürümleri kontrol edin)
  • Yapay zeka kurulum talimatları: https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
  • SDK deposu: https://github.com/OneSignal/OneSignal-Android-SDK
  • Android Studio: Meerkat | 2024.3.1+
  • Android API: Minimum 23+ (Android 6.0+), önerilen 31+ (Android 12+)
  • Cihaz/emülatör: Google Play Services yüklü Android 7.0+
  • Gerekli bağımlılık: com.onesignal:OneSignal:[5.6.1, 5.99.99]
  • Application sınıfı: Doğru SDK başlatma için gereklidir
  • App ID formatı: 36 karakterlik UUID (örnek: 12345678-1234-1234-1234-123456789012). Dashboard > Settings > Keys & IDs bölümünde bulabilirsiniz.
  • Başlatma: OneSignal.initWithContext(this, "YOUR_APP_ID")
  • Pil optimizasyonu: Arka plan bildirimlerini etkileyebilir
  • Önerilen: Cihazlar arasında kullanıcıları birleştirmek için OneSignal.login("user_id") ile External ID atayın

Android kurulum adımları

Aşağıdaki adımların sonunda şunlara sahip olacaksınız:
  • Android uygulamanızda yüklenmiş ve başlatılmış OneSignal SDK
  • Gerçek bir cihazda doğru şekilde görüntülenen push bildirim izni istemi
  • Başarıyla teslim edilmiş bir test push ve uygulama içi mesaj
Adım 0’ı (OneSignal’da FCM Yapılandırması) atladıysanız, aşağıdaki Android Studio kurulumunu yine de tamamlayabilirsiniz. Push bildirimlerini test etmeden veya göndermeden önce Adım 0’ı tamamlayın.

Adım 1. OneSignal SDK’sını ekleyin

  1. Android Studio’da build.gradle.kts (Module: app) veya build.gradle (Module: app) dosyanızı açın
  2. dependencies bölümünüze OneSignal’ı ekleyin:
OneSignal implementation bağımlılığı eklenmiş Android Studio app build.gradle.kts dosyası

Örnek, OneSignal'ı Uygulamanızın build.gradle.kts dosyasına eklemeyi göstermektedir.

  1. Gradle Senkronizasyonu: Görünen afişte Sync Now seçeneğine tıklayın veya File > Sync Project with Gradle Files yolunu izleyin
Gradle senkronizasyonunun bağımlılık çakışması olmadan başarıyla tamamlandığını doğrulayın.

Adım 2. Application sınıfını oluşturun ve yapılandırın

Tüm giriş noktalarında doğru SDK kurulumunu sağlamak için OneSignal’ı Application sınıfınızın onCreate metodunda başlatmak en iyi uygulamadır. Henüz yoksa bir Application sınıfı oluşturun:
  1. File > New > Kotlin Class/File (veya Java Class)
  2. Ad: ApplicationClass (veya tercih ettiğiniz ad)
Ad olarak ApplicationClass girilmiş Android Studio New Kotlin Class iletişim kutusu

Örnek, ApplicationClass adında yeni bir Kotlin sınıfı oluşturmayı göstermektedir.

Aşağıdaki OneSignal kodunu Application sınıfına ekleyin. YOUR_APP_ID kısmını Dashboard > Settings > Keys & IDs bölümündeki gerçek OneSignal App ID’nizle değiştirin.
Android Studio'da OneSignal initWithContext ve requestPermission gösteren ApplicationClass.kt

Örnek ApplicationClass.kt dosyası.

Bir Activity içinde (örneğin MainActivity) başlatma önerilmez çünkü derin bağlantılardan veya bildirimlerden gelen soğuk başlatmalarda çağrılmayabilir. Güvenilirlik için OneSignal’ı her zaman Application sınıfınızda başlatın.
Application sınıfını kaydedin:
  1. Uygulamanızın AndroidManifest.xml dosyasını açın
  2. <application> etiketinize android:name=".ApplicationClass" ekleyin (farklı bir ad belirlediyseniz .ApplicationClass kısmını gerçek sınıf adınızla değiştirin).
AndroidManifest.xml
<application> etiketinde tools:node="replace" olup olmadığına bakın. Bu işaret, OneSignal PermissionsActivity dahil kütüphaneden birleştirilen bileşenleri siler. Bildirim izin akışı o zaman ActivityNotFoundException ile çöker. tools:node="replace" öğesini kaldırın. Yalnızca bir özniteliği geçersiz kılmanız gerekiyorsa tools:replace="android:theme" (veya değiştirdiğiniz öznitelik) kullanın.
android:name değeri .ApplicationClass olarak ayarlanmış AndroidManifest.xml application etiketi

.ApplicationClass adıyla AndroidManifest.xml.

Uygulamanın hatasız derlenip çalıştığını doğrulayın.

Adım 3. Varsayılan bildirim simgelerini yapılandırın (önerilen)

Varsayılan zil simgesini ic_stat_onesignal_default adında bir küçük simgeyle değiştirin. Şeffaf arka plan üzerinde tek renkli bir siluet kullanın, aksi takdirde Android beyaz bir kare gösterecektir.
  1. Android Asset Studio ile farklı yoğunlukları oluşturun.
  2. ic_stat_onesignal_default dosyasını her yoğunluk klasörüne yerleştirin: res/drawable-mdpi/ (24×24) ile res/drawable-xxxhdpi/ (96×96) arasında.
Büyük simgeler, vurgu rengi ve Android 17 başlatıcı simgesi davranışı için Bildirim simgeleri sayfasına bakın.

Adım 4. Entegrasyonu test edin

Abonelik oluşturulmasını doğrulayın:
  1. Google Play Services yüklü bir cihaz veya emülatörde uygulamayı başlatın.
  2. Dashboard > Audience > Subscriptions bölümünü kontrol edin. Durum Never Subscribed gösterir.
  3. İzin istemi göründüğünde kabul edin.
  4. Dashboard’u yenileyin. Durum Subscribed olarak değişir.
Bildirimlere izin verilmesini isteyen Android push izin istemi

Android push izin istemi

'Never Subscribed' durumundaki Aboneliği gösteren Dashboard.

'Never Subscribed' durumundaki Aboneliği gösteren Dashboard

Push izinlerini verdikten sonra, Abonelik durumunun 'Subscribed' olarak güncellendiğini görmek için dashboard'u yenileyin.

Push izinlerini verdikten sonra, Abonelik durumunun 'Subscribed' olarak güncellendiğini görmek için dashboard'u yenileyin

Bir mobil Abonelik, kullanıcı uygulamanızı bir cihazda ilk kez açtığında veya aynı cihazda kaldırıp yeniden yüklediğinde oluşturulur. İzin istemini kabul ettikten sonra dashboard’daki durum Subscribed olarak görünmelidir.

Test kullanıcısı ve segment oluşturun

  1. Aboneliğin yanında Options > Add as test user seçeneğini seçin ve bir ad girin.
  2. Audience > Segments > New Segment bölümüne gidin.
  3. Ad: Test Users, filtre olarak Test Users ekleyin > Create Segment.
Bir abonelik kaydında Add as test user seçeneğinin vurgulandığı Options menüsü

Test kullanıcısı ekleyin

Test Users filtresiyle bir 'Test Users' segmenti oluşturun.

Test Users filtresiyle bir 'Test Users' segmenti oluşturun

Artık bu cihaza ve Test Users segmentine test mesajları gönderebilirsiniz.

API ile test push gönderin

  1. Settings > Keys & IDs bölümüne gidin.
  2. Sağlanan kodda, aşağıdaki koddaki YOUR_APP_API_KEY ve YOUR_APP_ID kısımlarını gerçek anahtarlarınızla değiştirin. Bu kod, daha önce oluşturduğumuz Test Users segmentini kullanır.
Push bildirimlerindeki görseller daraltılmış bildirim görünümünde küçük görünür. Tam görseli görmek için bildirimi genişletin.

Daraltılmış bildirim görünümünde görseller küçük görünür. Tam görseli görmek için bildirimi genişletin.

Onaylı teslimi gösteren teslim istatistikleri (ücretsiz planlarda kullanılamaz).

Onaylı teslimi gösteren teslim istatistikleri (ücretsiz planlarda kullanılamaz)

Test cihazının özel simgenizle (yapılandırıldıysa) ve genişletildiğinde büyük görselle bir bildirim aldığını doğrulayın. Ücretli planlarda Dashboard > Delivery > Sent Messages bölümü onaylı teslimi (Confirmed) gösterebilir.
  • Bildirim almadınız mı? Mobil push gösterilmiyor sayfasına bakın.
  • Özel simge yok mu? Simge adının ic_stat_onesignal_default olduğunu ve doğru drawable klasörlerinde bulunduğunu doğrulayın.
  • Sorun mu yaşıyorsunuz? API isteğini ve uygulama başlatılmasından sonuna kadar olan günlüğü bir .txt dosyasına kopyalayıp yapıştırın. Ardından her ikisini de support@onesignal.com adresiyle paylaşın.

Uygulama içi mesajları test edin

  1. Uygulamayı 30 saniyeden fazla kapatın
  2. Dashboard > Messages > In-App > New In-App > Welcome şablonunu seçin
  3. Hedef kitle: Test Users segmenti
  4. Tetikleyici: On app open
  5. Zamanlama: Every time trigger conditions are satisfied
  6. Make Message Live seçeneğine tıklayın
  7. Uygulamayı açın
'Test Users' segmentini uygulama içi mesajla hedefleme.

'Test Users' segmentini uygulama içi mesajla hedefleme

Uygulama içi Hoş Geldiniz mesajının örnek özelleştirmesi.

Uygulama içi Hoş Geldiniz mesajının örnek özelleştirmesi

Uygulama içi mesaj zamanlama seçenekleri.

Uygulama içi mesaj zamanlama seçenekleri

Cihazlarda gösterilen hoş geldiniz uygulama içi mesajı.

Cihazlarda gösterilen hoş geldiniz uygulama içi mesajı

Test cihazında Hoş Geldiniz uygulama içi mesajı gösterilmelidir. Daha fazla ayrıntı için Uygulama içi mesaj kurulumu sayfasına bakın.
Mesajı göremiyor musunuz?
  • Yeni bir oturum başlatın
  • Hâlâ Test Users segmentinde misiniz?
    • Uygulamayı yeniden yüklediyseniz veya cihaz değiştirdiyseniz, cihazı Test kullanıcılarına tekrar ekleyin ve Test Users segmentinin bir parçası olduğunu doğrulayın.
  • Sorun mu yaşıyorsunuz?
    • Yukarıdaki adımları tekrarlarken Hata Ayıklama Günlüğü Alma kılavuzunu takip edin. Bu, support@onesignal.com ile paylaşabileceğiniz ek günlük kaydı oluşturacak ve neler olduğunu araştırmanıza yardımcı olacağız.
Artık Aboneliklere, Test kullanıcılarına ve bir Segmente sahipsiniz. Mesaj oluşturma API’si ile görselli bir push ve bir uygulama içi mesaj gönderdiniz. Kullanıcıları tanımlamak ve daha fazla özellik eklemek için aşağıdan devam edin.
OneSignal SDK’sını başarıyla kurdunuz ve şu önemli kavramları öğrendiniz:Uygulamanızdaki kullanıcıları tanımlamak ve ek özellikleri ayarlamak için bu kılavuza devam edin.

Yaygın hatalar ve çözümler

Kullanıcı yönetimi

Daha önce mobil Abonelik oluşturmayı gösterdik. Şimdi OneSignal SDK’sını kullanarak tüm Abonelikleri (push, e-posta ve SMS dahil) genelinde Kullanıcıları tanımlamaya geçeceğiz.

External ID atayın (önerilen)

Cihazlar, e-posta adresleri ve telefon numaraları arasında kullanıcıları tutarlı bir şekilde tanımlamak için backend’inizin kullanıcı tanımlayıcısını kullanarak bir External ID atayın. Bu, mesajlaşmanın kanallar ve üçüncü taraf sistemler arasında birleşik kalmasını sağlar.
OneSignal, Abonelikler (Subscription ID) ve Kullanıcılar (OneSignal ID) için benzersiz salt okunur kimlikler oluşturur.SDK’mız aracılığıyla External ID ayarlamak, nasıl oluşturulduklarına bakılmaksızın kullanıcıları tüm abonelikleri genelinde tanımlamak için şiddetle önerilir.SDK referans kılavuzundaki login metodu hakkında daha fazla bilgi edinin.

Etiketler ve Özel Olaylar ekleyin

Etiketler ve Özel Olayların her ikisi de kullanıcılara veri ekler. Etiketler, kullanıcı özellikleri için (username, role veya status gibi) key-value dizeleridir. Özel Olaylar JSON kullanır ve genellikle eylemleri temsil eder (new_purchase veya abandoned_cart gibi). Her ikisi de Mesaj Kişiselleştirme ve Journeys’i destekleyebilir.
Daha fazla ayrıntı için Etiketler ve Özel Olaylar sayfalarına bakın.

E-posta ve/veya SMS abonelikleri ekleyin

Push bildirimlerine ek olarak e-posta ve SMS aracılığıyla kullanıcılara ulaşabilirsiniz. E-posta adresi veya telefon numarası OneSignal uygulamasında zaten mevcutsa, SDK bunu mevcut kullanıcıya ekler ve kopya oluşturmaz. Adresin tanımlanmış kullanıcıya eklenmesi için önce login() çağırın.
External ID ile birleştirilmiş push, e-posta ve SMS aboneliklerine sahip bir kullanıcı profili.

External ID ile birleştirilmiş push, e-posta ve SMS aboneliklerine sahip bir kullanıcı profili

Çok kanallı iletişim için en iyi uygulamalar
  • E-posta veya SMS abonelikleri eklemeden önce açık onay alın.
  • Her iletişim kanalının faydalarını kullanıcılara açıklayın.
  • Kullanıcıların tercih ettikleri kanalları seçebilmeleri için kanal tercihleri sunun.

Gizlilik ve kullanıcı onayı

OneSignal’ın kullanıcı verilerini ne zaman topladığını kontrol etmek için SDK’nın onay kapılama yöntemlerini kullanın. consentRequired metodunu initWithContext çağrısından önce çağırın.

Push izinleri isteme

Uygulama açılışında hemen requestPermission() çağırmak yerine daha stratejik bir yaklaşım benimseyin. İzin istemeden önce push bildirimlerinin değerini açıklamak için bir uygulama içi mesaj kullanın. En iyi uygulamalar ve uygulama ayrıntıları için Push izinleri isteme kılavuzumuza bakın.

Push, kullanıcı ve uygulama içi olayları dinleyin

Kullanıcı eylemlerine ve durum değişikliklerine tepki vermek için SDK dinleyicilerini kullanın. Bunları Application sınıfınızda OneSignal.initWithContext() çağrısından sonra ekleyin.

Push bildirim olayları

Kullanıcı durumu değişiklikleri

Bu örnek, push abonelik gözlemcisini kullanır. Kullanıcı durumu gözlemcisi ve bildirim izni gözlemcisi Mobil SDK referansı’nda mevcuttur.

Uygulama içi mesaj olayları

Ek uygulama içi mesaj yöntemleri Mobil SDK referansı’nda mevcuttur.

Gelişmiş kurulum ve özellikler

Android’e özgü özellikler

Evrensel özellikler

Tam SDK yöntem belgeleri için Mobil SDK referansı sayfasına bakın.

SSS

Android Studio neden OneSignal sembolünü çözümleyemiyor?

SDK bağımlılığı eksik veya Gradle senkronize edilmemiş. Uygulama modülünüzün build.gradle dosyasına com.onesignal:OneSignal:[5.6.1, 5.99.99] ekleyin ve File > Sync Project with Gradle Files yolunu kullanın.

Application sınıfım neden bulunamıyor?

Sınıf manifest’te kayıtlı değil. AndroidManifest.xml dosyasındaki <application> etiketine android:name=".ApplicationClass" (veya kendi sınıf adınızı) ekleyin.

Emülatör neden Google Play Services’in kullanılamadığını söylüyor?

Emülatör imajı Play Services içermiyor. Play Store’lu bir cihaz veya Google API’leri içeren bir emülatör sistem imajı kullanın.

Bildirim neden varsayılan Android simgesini gösteriyor?

Küçük simge eksik veya yanlış adlandırılmış. ic_stat_onesignal_default dosyasını her res/drawable-* yoğunluk klasörüne ekleyin. Bkz. Bildirim simgeleri.

Test cihazım neden push almadı?

FCM kimlik bilgileri yapılandırılmamış veya cihaz abone değil. Adım 0’ı tamamlayın ve Abonelik durumunun Subscribed olduğunu doğrulayın. Ardından Mobil push gösterilmiyor sayfasına bakın.

Uygulama içi mesajlar neden gösterilmiyor?

Uygulama içi mesajlar yeni bir oturum gerektirir. Uygulamayı zorla kapatın veya en az 30 saniye arka plana alın, ardından yeniden açın. Cihazın hâlâ Test Users segmentinde olduğunu doğrulayın. Bkz. Oturumlar ve uygulama içi mesajlar nasıl görüntülenir.

Manifest merger failed hatasına ne neden olur?

Çakışan <application> android:name değerleri veya yinelenen izinler. Birleşik manifest’inizde ikinci bir Application sınıfı arayın ve tek bir android:name tutun.

Pil optimizasyonları bildirimleri neden engelliyor?

Bazı OEM’ler arka plan çalışmasını kısıtlar. Cihaz uyku moduna geçtikten sonra bildirimler durursa, kullanıcılardan uygulamanız için pil optimizasyonunu devre dışı bırakmalarını isteyin.

Daha fazla günlük çıktısını nasıl alabilirim?

OneSignal.Debug.logLevel = LogLevel.VERBOSE (Kotlin) veya OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE) (Java) ayarlayın, sorunu yeniden oluşturun ve logcat çıktısını yakalayın. Bkz. Hata ayıklama günlüğü alma.
Yardıma mı ihtiyacınız var?Destek ekibimizle sohbet edin veya support@onesignal.com adresine e-posta gönderinLütfen şunları ekleyin:
  • Yaşadığınız sorunun ayrıntıları ve varsa yeniden üretme adımları
  • OneSignal Uygulama Kimliğiniz
  • Varsa Harici ID veya Abonelik ID
  • Varsa OneSignal Panosunda test ettiğiniz mesajın URL’si
  • İlgili günlükler veya hata mesajları
Size yardımcı olmaktan mutluluk duyarız!