Live Activities geliştirici kurulumu

​

Gereksinimler

• Yerel iOS (Swift/Objective-C) kullanıyorsanız iOS SDK kurulumu’nu takip edin.
  • Bir sarmalayıcı SDK (React Native, Flutter, Unity, vb.) kullanıyorsanız Mobil SDK kurulumu’nu ve ardından Çapraz platform Live Activity SDK Kurulumu’nu takip edin.
• push-to-start desteği için OneSignal iOS SDK sürüm 5.2.0+ (sürüm notlarına bakın).
• iOS 16.1+ ve iPadOS 17+
• Bir .p8 APNs anahtarı kullanın. Apple, Live Activities ile p12 sertifikalarını desteklemiyor.
• Xcode 14 veya üzeri

​

Kurulum

​

1. Widget Extension ekleyin

Xcode'da uygulamanız için yeni bir Widget Extension hedefi ekleyin.

Bir Live Activity için Widget Extension seçenekleri.

Bir Live Activity için Widget Extension seçenekleri.

​

2. Info.plist’i güncelleyin

Info'ya Supports Live Activities anahtarını ekleyin ve değerini Boolean YES olarak ayarlayın

<key>NSSupportsLiveActivities</key>
<true/>

​

3. SDK ekleyin

• Package Manager
• Cocoapods

Widget Extension hedefinizde, General > Frameworks, Libraries and Embedded Content altına OneSignalFramework’ü ekleyin:

Widget Extension hedefinize OneSignalFramework'ü ekleyin

​

4. Widget özniteliklerini ve UI’ı tanımlayın

• your-nameAttributes, Live Activity’nizin statik içeriğini açıklar.
• ContentState, Live Activity’nizin dinamik içeriğini açıklar.

import ActivityKit
import WidgetKit
import SwiftUI
// Import the OneSignalLiveActivities module
// If you get an error about the module not being found, return to step 3 and ensure you have added the OneSignalLiveActivities pod correctly.
import OneSignalLiveActivities

// Update to inherit from OneSignalLiveActivityAttributes
// This will be used in your API requests to start a Live Activity
struct OneSignalWidgetAttributes: OneSignalLiveActivityAttributes  {
    // Update to inherit from OneSignalLiveActivityContentState
    public struct ContentState: OneSignalLiveActivityContentState {
        // Dynamic stateful properties about your activity go here!
        var emoji: String
        // Add a reference to OneSignalLiveActivityContentStateData?
        var onesignal: OneSignalLiveActivityContentStateData?
    }
    // Fixed non-changing properties about your activity go here!
    var name: String
    // Add a reference to OneSignalLiveActivityAttributeData
    var onesignal: OneSignalLiveActivityAttributeData
}

struct OneSignalWidgetLiveActivity: Widget {
    var body: some WidgetConfiguration {
      // Update to use `for: the-name-of-your-attributes-struct`
      // This will be used in your API requests to start a Live Activity
        ActivityConfiguration(for: OneSignalWidgetAttributes.self) { context in
            // Lock screen/banner UI goes here
            // Update to show the attributes sent via the payload
            VStack {
                Text("Hello \(context.attributes.name) \(context.state.emoji)")
            }
            .activityBackgroundTint(Color.cyan)
            .activitySystemActionForegroundColor(Color.black)

        } dynamicIsland: { context in
            DynamicIsland {
                // Expanded UI goes here.  Compose the expanded UI through
                // various regions, like leading/trailing/center/bottom
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text("Trailing")
                }
                DynamicIslandExpandedRegion(.bottom) {
                    Text("Bottom \(context.state.emoji)")
                    // more content
                }
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T \(context.state.emoji)")
            } minimal: {
                Text(context.state.emoji)
            }
            .widgetURL(URL(string: "http://www.apple.com"))
            .keylineTint(Color.red)
        }
    }
}

​

5. Ana hedef üyeliğine izin verin

Ana hedef üyeliğine izin verin

​

6. AppDelegate’inize setup metodunu ekleyin

// Import the OneSignalLiveActivities module
import OneSignalLiveActivities

// This should be added after initializing the OneSignal SDK
if #available(iOS 16.1, *) {
	OneSignal.LiveActivities.setup(OneSignalWidgetAttributes.self)
  // If you have multiple Live Activities, you can add them here with the setup method
  // OneSignal.LiveActivities.setup(LiveActivityWidgetAttributes-2.self)
}

​

Bir Live Activity başlatma

• Push-to-start
• Trigger-in-app

Bir Push To Start API isteği gönderin. Tüm adların ve kimliklerin widget yapılandırmanızla tam olarak eşleştiğinden emin olun (parametreler büyük/küçük harfe duyarlıdır). Herhangi bir şey eksikse veya yanlış eklenmişse, widget’ı başlatmaya çalışırken sorunlarla karşılaşabilirsiniz.İşte yukarıdaki örnek için çalışacak bir örnek istek.Değiştirin:

• YOUR_APP_ID’yi OneSignal App ID’niz ile.
• YOUR_APP_API_KEY’i OneSignal API anahtarınız ile.
• OneSignalWidgetAttributes’ı Widget Attributes struct’ınızın adıyla.
  curl

  Copy

  Ask AI

  curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/activities/activity/OneSignalWidgetAttributes' \
  --header 'Authorization: key YOUR_APP_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "event": "start",
      "activity_id": "push-to-start",
      "included_segments": [
          "Subscribed Users"
      ],
      "event_attributes": {
          "name": "World"
      },
      "event_updates": {
          "emoji":"🤩"
      },
      "name": "Live Activities Test",
      "contents": {
          "en": "A push started this Live Activity"
      },
      "headings": {
        "en": "Live Activity Started"
      }
    }'
  

Sağlanan örnek kodu takip ediyorsanız, cihazınızın kilit ekranında Live Activity’yi görmelisiniz.

Kilit ekranında Live Activity

Push-to-start ile bir Live Activity’yi başarıyla başlattınız!Kullanıcıların güncellemeleri almaya devam etmek için “Allow” seçmesi gerekecektir.

​

Bir Live Activity’yi güncelleme

curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/push-to-start/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "update",
    "event_updates": {
        "emoji": "😎"
    },
    "contents": {
        "en": "A push updated this Live Activity"
    },
    "name": "Live Activity Updated"
}'

Live Activity Güncellendi

​

Bir Live Activity’yi sonlandırma

curl --location 'https://api.onesignal.com/apps/YOUR_APP_ID/live_activities/my_activity_id/notifications' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: key YOUR_API_KEY' \
--data '{
    "event": "end",
    "event_updates": {
        "emoji": "👋"
    },
    "contents": {
        "en": "A push ended this Live Activity"
    },
    "name": "Live Activity Ended"
}'

• SDK’mızın exit() metodunu kullanın.
• Kullanıcı Live Activity’yi manuel olarak kaydırarak kapatır.
• Kullanıcı iOS Ayarlarında Live Activities için izni iptal eder.

Live Activity Sonlandı

​

En iyi uygulamalar ve öneriler

​

Tasarım değerlendirmeleri

• Apple’ın Live Activities İnsan Arayüzü Yönergelerini takip edin.
  • Hızlı bir bakışta anlaşılması kolay olması için önemli bilgilere öncelik verin.
  • Uygulamanıza Dynamic Island’a dikkat çeken öğeler eklemeyin.
  • Kenar boşlukları kullanın ve öğeler arasında boşluk bırakın.
  • Arka plan için kalın bir renk kullanın. Hem Light hem de Dark mode için tasarlayın.

​

İşlevsellik

• Apple, her Live Activity sunumunun desteklenmesini gerektirir.
  • Compact
  • Minimal
  • Expanded
  • Lock Screen
• Derin bağlantılarınızı test edin.
• Apple’ın Live Activities ile Canlı Veri Görüntüleme kılavuzunu inceleyin.
• Bir Live Activity’de hassas bilgileri görüntülemekten kaçının.

​

Yedek mesaj ayarlama

• Kullanıcının live activity’sine güncelleme alamadığı belirli durumlarda, biri başlatıldıktan sonra, uygulamayı açmak devam etmek için onları yenilemelidir
  • Bunu hesaba katmak için, stale date’i gelecekte bir tarih ve saate, kullanıcıya ilk güncellemenizi göndereceğinizi bildiğiniz bir zamandan sonraya ayarlarsınız ve güncellemeyi almayanlar yedek mesajı görürler.
  • Widget UI’ınızda yedek mesajı göstermek için bu “stale” durumunu dinleyebilirsiniz:
  swift

  Copy

  Ask AI

    struct ptsLiveActivity: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ptsAttributes.self) { context in
            //This will flip to true after the stale date
            let isStale = context.isStale 
            if !isStale{
                VStack {
                    Text("\(context.attributes.name) \(context.state.emoji)")
                        .activityBackgroundTint(Color.cyan)
                        .activitySystemActionForegroundColor(Color.black)
                }
            }  else {
            //If the message is stale, we request the user clicks the widget to open the app
                VStack {
                    Text("Something went wrong, please click to refresh")
                }
            }
    //... Rest of the widget UI
    }
  

---

## SSS

### Yüksek öncelikli güncellemeler için bütçe nedir?

Apple, yüksek öncelikli (`priority: 10`) güncellemeler için sabit bir sınır sağlamaz, ancak dinamik bir sistem düzeyinde bütçe uygularlar. Kısa bir süre içinde çok fazla yüksek öncelikli güncelleme göndermek, güncellemelerin geciktirildiği veya düşürüldüğü kısıtlamaya neden olabilir.

Kısıtlama riskini azaltmak için:
- Öncelik düzeylerinin karışımını kullanın: Apple, denge için hem `priority: 5` (standart) hem de `priority: 10` (yüksek) kullanılmasını önerir.
- `priority: 10`'u yalnızca zamana duyarlı veya kritik güncellemeler için ayırın (örn. sipariş durumu değişiklikleri, oyun skorları).

Kullanım durumunuz sık güncellemeler gerektiriyorsa:
- Uygulamanızın `Info.plist` dosyasına `NSSupportsLiveActivitiesFrequentUpdates` anahtarını Boolean `YES` olarak ayarlanmış şekilde ekleyin.
- Bu bütçe aşıldığında, iOS kullanıcıdan ek güncellemelere izin vermesini isteyebilir. Kullanıcı kabul ederse, Apple sorunsuz bir deneyim sürdürmek için izin verilen güncelleme sınırını otomatik olarak genişletecektir.

Daha fazla ayrıntı için [Apple'ın Geliştirici Belgelerine](https://developer.apple.com/documentation/activitykit/starting-and-updating-live-activities-with-activitykit-push-notifications#Determine-the-update-frequency) bakın.

### Ana uygulamadan Live Activity güncellemelerini okuyabilir miyim?

Evet. Hata ayıklama veya UI senkronizasyonu için güncellemeleri gözlemleyebilirsiniz:

```swift
Task {
    for await content in activity.contentUpdates {
        print("LA activity id: \(activity.id), content update: \(content.state)")
    }
}
// Example output:
// LA activity id: EFE6D54D-F7E1-45EF-9514-4C2598F8DED2, content update: ContentState(message: "My message from payload")

Task {
    for await state in activity.activityStateUpdates {
        print("LA state update: \(state)")
        //If you wanted to do something based on the state, you would use this:
      	if state != ActivityState.active {
            //Do something here
        }
    }
}

// Example output 1 - LA ended, but still visible
// LA state update: active

/* State can be equal to 4 possible values on the ActivityState enum
active, dismissed, ended, and stale
*/

​

API abone sınırını aştığımı belirten bir hata mesajıyla 400 döndürdü. Ne yapmalıyım?

​

Hem push hem de Live Activities göndermeyi nasıl önlerim?

​

Sorun giderme

​

Alıcı yok

1. Sunucuya doğru biçimlendirilmiş bir istek gönderdiğinizden emin olmak için isteğinizdeki yol parametrelerini kontrol edin. Uygulama Kimliği, OneSignal.Initialize metodunda kullanılan Uygulama Kimliğiniz ile eşleşmeli ve activity türü, Live Activity dosyanızda tanımladığınız türle eşleşmelidir.
2. Push To Start API isteğinin gövdesinde aşağıdaki parametrelere sahip olmalısınız:

• event: "start"
• event_updates: Activity türü altında struct’ınızda tanımladığınız ve widget’ınızda kullanılan dinamik veri. Harf büyüklüğü ve değişkenlerin istek, tür ve widget arasında eşleştiğinden emin olun.
• event_attributes: Statik veri Event Updates ile aynı mantığı izler ve kullanımdaki tüm değişkenleri içermeli ve live activity’nin tüm kısımları ve istek arasında eşleşmelidir
• activity_id: Bu, widget’a bir kimlik atayacaktır ve kullanıcının cihazında başlatıldıktan sonra activity’yi güncellemek için kullanılacak olan şeydir.
• name: Live Activity Adı.
• contents: Push göndermek için gereken mesaj içeriği.
• headings: Push göndermek için gereken mesaj başlığı.
• included_segments gibi bir hedefleme parametresi. Mevcut seçenekler.

​

Activity gönderildi, ancak alınmadı

1. İsteğin doğru biçimlendirildiğinden emin olun. Widget’ta kullanılan herhangi bir alan atlanırsa, activity beklendiği gibi başlatılamayabilir veya güncellenemeyebilir.
2. API isteğinizde, ayarladığınız priority düzeyini belirleyin. Bunu 10 (en yüksek öncelik) olarak ayarlıyorsanız, 5’e düşürmeyi deneyin ve tekrar test edin. Apple, kendi dahili hız limitleri uyarınca çok sık gönderilen istekleri kısıtlayacaktır.