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).
• tıklama takibi ve Onaylanmış Teslimat için OneSignal iOS SDK sürüm 5.2.15+
• 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

​

2. Info.plist’i güncelleyin

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

​

3. SDK ekleyin

• Package Manager
• Cocoapods

Bir sarmalayıcı SDK (örneğin Flutter) kullanıyorsanız ve SPM etkinse, bu adımı atlayabilirsiniz. OneSignal paketi zaten çözülmüş olup tüm hedefler için kullanılabilir.

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

Projenizin Targets listesinde widget extension hedefinizin adını bulun. Örneğin adı OneSignalWidgetExtension’dır.

Podfile dosyanızı açın ve aşağıdaki kodu ekleyin. OneSignalWidgetExtension’ı widget extension hedefinizin adıyla değiştirin.

Podfile

Full Podfile example

target 'OneSignalWidgetExtension' do
  use_frameworks!
  pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
end

# Uncomment the next line to define a global platform for your project
# platform :ios, '9.0'

target 'Demo Momenta' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
  pod 'OneSignal/OneSignalInAppMessages', '>= 5.0.0', '< 6.0'
end

target 'OneSignalNotificationServiceExtension' do
  use_frameworks!
  pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
end

target 'OneSignalWidgetExtension' do
  use_frameworks!
  pod 'OneSignal/OneSignal', '>= 5.0.0', '< 6.0'
end

Xcode’u kapatın ve OneSignalLiveActivities pod’unu yüklemek için pod repo update && pod install komutunu çalıştırın.Bunu yaptıktan sonra “No such module ‘OneSignalLiveActivities’” hatasını görmeye devam ederseniz, bağımlılığı manuel olarak “Widget Extension Target” > General > Frameworks and Libraries > + simgesi’ne giderek ekleyebilirsiniz. OneSignalLiveActivities framework’ünü seçin:

​

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

​

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

  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.

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 kullanıcının uygulamanızla etkileşim halindeyken bir Live Activity tetiklemesini sağlayabilirsiniz.Örneğin, bir kullanıcının devam eden aktif bir olayı olduğunda (sipariş verdiler, oyun devam ediyor, bir etkinlik başlamak üzere, vb.) ve uygulamanızı açtığında, otomatik olarak bir Live Activity görüntüleyebilirsiniz.Bu örnekte Live Activity’yi manuel olarak başlatmak için bir düğme kullanacağız.

import SwiftUI
import ActivityKit
import OneSignalFramework
import OneSignalLiveActivities

struct ContentView: View {
  @StateObject private var viewModel = LiveActivityViewModel()

  var body: some View {
    VStack {
      Button("Start Live Activity") {
        viewModel.startLiveActivity()
      }
    }
  }
}

class LiveActivityViewModel: ObservableObject {

  func startLiveActivity() {
    let osAttributes = OneSignalLiveActivityAttributeData.create(activityId: "click-to-start")
    let attributes = OneSignalWidgetAttributes(name: "OneSignal", onesignal: osAttributes)
    let contentState = OneSignalWidgetAttributes.ContentState(emoji:"🤩", onesignal: nil)
    do {
        let activity = try Activity<OneSignalWidgetAttributes>.request(
            attributes: attributes,
            contentState: contentState,
            pushType: .token)
    } catch {
        print(error.localizedDescription)
    }
  }
}

Düğmeye tıklandığında Live Activity başlatılacaktır.

​

Live Activity tıklamalarını izleme

​

Adım 1: Widget’ınıza tıklama izleme ekleme

import OneSignalLiveActivities

struct ExampleAppFirstWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: ExampleAppFirstWidgetAttributes.self) { context in
            VStack {
                Spacer()
                Text("Sample Text " + context.attributes.title).font(.headline)
                // Other UI code
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Pass nil if you don't need deep linking: .onesignalWidgetURL(nil, context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                DynamicIslandExpandedRegion(.leading) {
                    Text("Leading")
                }
                // Other Dynamic Island regions
            } compactLeading: {
                Text("L")
            } compactTrailing: {
                Text("T")
            } minimal: {
                Text("Min")
            }
            .onesignalWidgetURL(URL(string: "myapp://settings"), context: context)
            // Optional: Track Dynamic Island clicks separately
        }
    }
}

• Derin bağlantı için bir URL geçirebilir veya yalnızca navigasyon olmadan tıklama izleme istiyorsanız nil geçirebilirsiniz
• .onesignalWidgetURL() kullanıyorsanız görünüm hiyerarşisi Apple’ın .widgetURL() değiştiricisini içeremez
• Her ikisindeki tıklamaları izlemek istiyorsanız değiştiriciyi hem ana Live Activity görünümüne hem de Dynamic Island’a uygulayın

​

Adım 2: Uygulamanızda URL’leri işleme

import OneSignalLiveActivities

// AppDelegate example:
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)

    // Handle the original URL and navigate user
    if let url = originalURL {
        // Your custom URL routing logic
        return handleDeepLink(url)
    }
    return false
}

// SceneDelegate example:
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
    guard let url = URLContexts.first?.url else { return }

    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)

    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

// SwiftUI example:
.onOpenURL { url in
    let originalURL = OneSignal.LiveActivities.trackClickAndReturnOriginal(url)

    if let url = originalURL {
        // Your custom URL routing logic
        handleDeepLink(url)
    }
}

​

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"
}'

​

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.

​

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

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?

• Ö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ı).

• 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.

​

Ana uygulamadan Live Activity güncellemelerini okuyabilir miyim?

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.