Swift のライブアクティビティ

Swift Braze SDK 用にライブアクティビティを実装する方法について説明します。ライブアクティビティは、ロック画面に直接表示される永続的でインタラクティブな通知で、ユーザーはデバイスのロックを解除することなく、ダイナミックなリアルタイム更新を得ることができます。

仕組み

ライブアクティビティは、静的情報と更新可能な動的情報を組み合わせて表示します。たとえば、配達のステータス追跡機能を提供するライブアクティビティを作成できます。このライブアクティビティには、会社名が静的情報として含まれ、さらに配達ドライバーが目的地に近づくにつれて更新される「配達までの時間」が動的情報として含まれます。

開発者はBrazeを使用して、ライブアクティビティのライフサイクルを管理し、Braze REST APIを呼び出してライブアクティビティの更新を行い、サブスクライブ済みのすべてのデバイスが可能な限り早く更新を受信できるようにすることができます。また、Brazeでライブアクティビティを管理しているため、プッシュ通知、アプリ内メッセージ、Content Cardsなど、その他のメッセージングチャネルと連携させて活用を促進できます。

シーケンス図

• live activities sequence diagram

---
config:
  theme: mc
---
sequenceDiagram
  participant Server as Client Server
  participant Device as User Device
  participant App as iOS App / Braze SDK
  participant BrazeAPI as Braze API
  participant APNS as Apple Push Notification Service
  Note over Server, APNS: Launch Option 1<br/>Locally Start Activities
  App ->> App: Register a Live Activity using <br>`launchActivity(pushTokenTag:activity:)`
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Launch Option 2<br/>Remotely Start Activities
  Device ->> App: Call `registerPushToStart`<br>to collect push tokens early
  App ->> BrazeAPI: Push-to-start tokens sent to Braze
  Server ->> BrazeAPI: POST /messages/live_activity/start
  Note right of BrazeAPI: Payload includes:<br>- push_token<br>- activity_id<br>- external_id<br>- event_name<br>- content_state (optional)
  BrazeAPI ->> APNS: Live activity start request
  APNS ->> Device: APNS sends activity to device
  App ->> App: Get push token from iOS
  App ->> BrazeAPI: Activity ID & Push token<br>automatically sent to Braze
  Note over Server, APNS: Resuming activities upon app launch
  App ->> App: Call `resumeActivities(ofType:)` on each app launch
  Note over Server, APNS: Updating a Live Activity
  loop update a live activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Payload includes changes<br>to ContentState (dynamic variables)
  BrazeAPI ->> APNS: Update sent to APNS
  APNS ->> Device: APNS sends update to device
  end
  Note over Server, APNS: Ending a Live Activity
  Server ->> BrazeAPI: POST /messages/live_activity/update
  Note right of BrazeAPI: Activity can be ended via:<br> - User manually dismisses<br>- Times out after 12 hours<br>- Setting `end_activity: true` on `/messages/live_activity/update`
  APNS ->> Device: Live activity is dismissed

ライブアクティビティの実装

前提条件

この機能を使う前に、Swift Braze SDKを統合する必要がある。 以下の項目も完了する必要があります。

• プロジェクトがiOS 16.1以降をターゲットにしていることを確認します。
• XcodeプロジェクトのSigning & CapabilitiesにPush Notificationエンタイトルメントを追加します。
• 通知の送信に.p8キーが使用されていることを確認します。.p12や.pemなどの古いファイルはサポートされていません。
• Braze Swift SDKのバージョン8.2.0以降では、ライブアクティビティをリモートで登録できます。この機能を使用するには、iOS 17.2以降が必要です。

ステップ 1: アクティビティを作成する

まず、Appleのドキュメントのライブアクティビティでライブデータを表示する手順に従い、iOSアプリケーションにライブアクティビティをセットアップします。このタスクの一部として、Info.plistにNSSupportsLiveActivitiesをYESに設定して含めてください。

ライブアクティビティの正確な内容はビジネスケースに固有であるため、Activityオブジェクトを設定して初期化する必要があります。以下を定義することが重要です。

• ActivityAttributes: このプロトコルは、ライブアクティビティに表示される静的（不変）コンテンツと動的（可変）コンテンツを定義します。
• ActivityAttributes.ContentState: この型は、アクティビティの進行に伴って更新される動的データを定義します。

また、SwiftUIを使用して、サポートされているデバイスでロック画面とダイナミックアイランドのUI表示を作成します。

ライブアクティビティに関するAppleの前提条件と制限をよく理解してください。これらの制約はBrazeとは独立しています。

例

競争している2つの野生動物救助チームに、保護しているフクロウに対してポイントが与えられるSuperb Owlショーの更新をユーザーに提供するライブアクティビティを作成すると想定してみましょう。この例では、SportsActivityAttributesという構造体を作成しましたが、ActivityAttributesの独自の実装を使用することもできます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
struct SportsActivityAttributes: ActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String
}

ステップ 2: アクティビティを開始する

まず、アクティビティの登録方法を選択します。

• リモート: registerPushToStartメソッドをユーザーライフサイクルの早い段階で、push-to-startトークンが必要になる前に呼び出し、/messages/live_activity/startエンドポイントを使用してアクティビティを開始します。
• ローカル: ライブアクティビティのインスタンスを作成し、launchActivityメソッドを使用して、Brazeが管理するプッシュトークンを作成します。

• remote
• local

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@available(iOS 16.1, *)
// 1. Add the `BrazeLiveActivityAttributes` conformance to your `ActivityAttributes` struct.
struct SportsActivityAttributes: ActivityAttributes, BrazeLiveActivityAttributes {
  public struct ContentState: Codable, Hashable {
    var teamOneScore: Int
    var teamTwoScore: Int
  }

  var gameName: String
  var gameNumber: String

  // 2. Add the `String?` property to represent the activity ID.
  var brazeActivityId: String?
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {

  @available(iOS 17.2, *)
  func registerActivityType() {
    // This method returns a Swift background task.
    // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
    let pushToStartObserver: Task = Self.braze?.liveActivities.registerPushToStart(
      forType: Activity<SportsActivityAttributes>.self,
      name: "SportsActivityAttributes"
    )
  }

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

class LiveActivityManager {

  @available(iOS 16.2, *)
  func createActivity() {
    let activityAttributes = SportsActivityAttributes(gameName: "Superb Owl", gameNumber: "Game 1")
    let contentState = SportsActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0")
    let activityContent = ActivityContent(state: contentState, staleDate: nil)
    if let activity = try? Activity.request(attributes: activityAttributes,
                                            content: activityContent,
      // Setting your pushType as .token allows the Activity to generate push tokens for the server to watch.
                                            pushType: .token) {
      // Register your Live Activity with Braze using the pushTokenTag.
      // This method returns a Swift background task.
      // You may keep a reference to this task if you need to cancel it wherever appropriate, or ignore the return value if you wish.
      let liveActivityObserver: Task = AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "sports-game-2024-03-15",
                                                                                        activity: activity)
    }
  }

}

ステップ 3: アクティビティトラッキングを再開する

Brazeがアプリ起動時にライブアクティビティを追跡できるようにするには、次の手順を実行します。

1. AppDelegateファイルを開きます。
2. 使用可能な場合は、ActivityKitモジュールをインポートします。
3. アプリケーションで登録したすべてのActivityAttributesタイプについて、application(_:didFinishLaunchingWithOptions:)でresumeActivities(ofType:)を呼び出します。

これにより、Brazeはすべてのアクティブなライブアクティビティのプッシュトークン更新を追跡するタスクを再開できます。ユーザーがデバイス上のライブアクティビティを明示的に削除した場合、そのアクティビティは削除されたと見なされ、Brazeはそれを追跡しなくなります。

例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import UIKit
import BrazeKit

#if canImport(ActivityKit)
  import ActivityKit
#endif

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

  static var braze: Braze? = nil

  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {

    if #available(iOS 16.1, *) {
      Self.braze?.liveActivities.resumeActivities(
        ofType: Activity<SportsActivityAttributes>.self
      )
    }

    return true
  }
}

ステップ 4: アクティビティを更新する

/messages/live_activity/updateエンドポイントを使用すると、Braze REST APIを介して渡されたプッシュ通知を通じてライブアクティビティを更新できます。このエンドポイントを使用して、ライブアクティビティのContentStateを更新します。

ContentStateを更新すると、ライブアクティビティウィジェットに新しい情報が表示されます。前半終了時のSuperb Owlショーの表示例を以下に示します。

詳細については、/messages/live_activity/updateエンドポイントの記事を参照してください。

ステップ 5: アクティビティを終了する

ライブアクティビティがアクティブな場合、ユーザーのロック画面とダイナミックアイランドの両方に表示されます。Brazeを通じて終了するには、/messages/live_activity/updateエンドポイントでend_activityをtrueに設定します。

ライブアクティビティの終了の信頼性を向上させるには、以下のオプションの手順を実行します。

1. 同じupdateリクエストにオプションでdismissal_dateを含め、iOSがライブアクティビティUIを削除するタイミングを指定します。
2. メッセージアクティビティログで配信結果を確認します。

自動削除の設定

自動削除を設定するには、ライブアクティビティを開始した後に、更新エンドポイントへのフォローアップリクエストをスケジュールします。

1. 追跡可能なactivity_idを含む/messages/live_activity/startリクエストを送信します。
2. そのactivity_idとターゲット終了時刻をバックエンドスケジューラーに保存します。
3. ターゲット終了時刻に、end_activityをtrueに設定した/messages/live_activity/updateリクエストを送信します。
4. 同じ更新リクエストで削除日を設定します。詳細については、/messages/live_activity/updateエンドポイントを参照してください。

削除のタイミングはiOSによって制御されることに注意してください。有効な終了リクエストを送信した後でも、ロック画面やダイナミックアイランドからの削除は、OSレベルの条件に基づいて遅延したり、異なる動作をしたりする場合があります。

ライブアクティビティはBrazeの外部でも終了できます。

• ユーザーによる削除: ユーザーは手動でライブアクティビティを削除できます。
• タイムアウト: デフォルトの8時間が経過すると、iOSはユーザーのダイナミックアイランドからライブアクティビティを削除します。デフォルトの12時間が経過すると、iOSはユーザーのロック画面からライブアクティビティを削除します。

詳細については、/messages/live_activity/updateエンドポイントの記事を参照してください。

ライブアクティビティのトラッキング

ライブアクティビティのイベントは、Currents、Snowflakeデータ共有、およびクエリビルダーで利用できます。以下のイベントは、ライブアクティビティのライフサイクルの理解と監視、トークンの利用可能性の追跡、問題の独立した診断や配信ステータスの確認に役立ちます。

• ライブアクティビティのPush To Startトークン変更: push-to-start（PTS）トークンがBrazeで追加または更新されたタイミングをキャプチャし、ユーザーごとのトークン登録状況と利用可能性を追跡できます。
• ライブアクティビティ更新トークンの変更: ライブアクティビティ更新（LAU）トークンの追加、更新、または削除を追跡します。
• ライブアクティビティ送信: Brazeによってライブアクティビティが開始、更新、または終了されるたびにログを記録します。
• ライブアクティビティの結果: Brazeから送信された各ライブアクティビティについて、Appleプッシュ通知サービス（APNs）への最終的な配信ステータスを示します。

よくある質問（FAQ）

機能とサポート

ライブアクティビティをサポートしているプラットフォームは？

現在、ライブアクティビティはiOSとiPadOSに固有の機能です。デフォルトでは、iPhoneやiPadで起動したアクティビティは、ペアリングされたwatchOS 11以降またはmacOS 26以降のデバイスにも表示されます。

ライブアクティビティの記事では、Braze Swift SDKを使用してライブアクティビティを管理するための前提条件について説明しています。

React Nativeアプリはライブアクティビティをサポートしていますか？

はい、React Native SDK 3.0.0以降は、Braze Swift SDK経由でライブアクティビティをサポートしています。つまり、Braze Swift SDKの上に直接React Native iOSのコードを記述する必要があります。

Appleが提供するライブアクティビティ機能は、JavaScriptでは変換できない言語機能（Swift Concurrency、generics、SwiftUIなど）を使用しているため、ライブアクティビティ用のReact Native固有のJavaScriptコンビニエンスAPIは存在しません。

BrazeはCampaignやCanvasステップとしてのライブアクティビティをサポートしていますか？

いいえ、現在サポートされていません。

プッシュ通知とライブアクティビティ

ライブアクティビティがアクティブな状態でプッシュ通知が送信された場合はどうなりますか？

ライブアクティビティとプッシュ通知は異なる画面領域を占有するため、ユーザーの画面上で競合することはありません。

ライブアクティビティがプッシュメッセージ機能を活用する場合、ライブアクティビティを受信するためにプッシュ通知を有効にする必要がありますか？

ライブアクティビティは更新にプッシュ通知を利用しますが、異なるユーザー設定によって制御されています。ユーザーはライブアクティビティにオプトインしつつプッシュ通知はオプトアウトでき、その逆も可能です。

ライブアクティビティ更新トークンは8時間後に期限切れになります。

ライブアクティビティにはプッシュプライマーが必要ですか？

プッシュプライマーは、ユーザーにアプリからのプッシュ通知をオプトインするよう促すベストプラクティスです。しかし、ライブアクティビティにオプトインするためのシステムプロンプトはありません。デフォルトでは、ユーザーがiOS 16.1以降でアプリをインストールすると、そのアプリのライブアクティビティにオプトインされます。この権限は、アプリごとにデバイス設定で無効化または再有効化できます。

技術的なトピックとトラブルシューティング

ライブアクティビティにエラーがあるかどうかを確認するには？

ライブアクティビティのエラーは、Brazeダッシュボードのメッセージアクティビティログに記録されます。ここで「LiveActivity Errors」でフィルターできます。

push-to-start通知を送信した後、ライブアクティビティを受信できないのはなぜですか？

まず、messages/live_activity/startエンドポイントで説明されているすべての必須フィールドがペイロードに含まれていることを確認します。activity_attributesおよびcontent_stateフィールドは、プロジェクトのコードで定義されているプロパティと一致する必要があります。ペイロードが正しいことが確かな場合は、APNsによってレート制限されている可能性があります。この制限はBrazeではなくAppleによって課されています。

push-to-start通知がデバイスに正常に届いたがレート制限のために表示されなかったことを確認するには、Macのコンソールアプリを使用してプロジェクトをデバッグします。目的のデバイスの記録プロセスをアタッチし、検索バーでprocess:liveactivitiesdを使用してログをフィルタリングします。

push-to-startでライブアクティビティを開始した後、新しい更新を受信しないのはなぜですか？

上記の手順が正しく実装されていることを確認してください。ActivityAttributesには、BrazeLiveActivityAttributesプロトコルへの準拠とbrazeActivityIdプロパティの両方が含まれている必要があります。

ライブアクティビティのpush-to-start通知を受信したら、Braze URLの/push_token_tagエンドポイントへの送信ネットワークリクエストが表示され、"tag"フィールドの下に正しいアクティビティIDが含まれていることを再確認してください。

最後に、更新ペイロード内のライブアクティビティ属性タイプが、SDKメソッド呼び出しのregisterPushToStartで使用した文字列とクラスに完全に一致していることを確認してください。定数を使用してタイプミスを防いでください。

live_activity/updateエンドポイントを使用しようとすると、アクセス拒否の応答が返されます。なぜですか？

使用するAPIキーには、さまざまなBraze APIエンドポイントにアクセスするための適切な権限を付与する必要があります。以前に作成したAPIキーを使用している場合、権限の更新を忘れている可能性があります。APIキーセキュリティの概要を確認してください。

messages/sendエンドポイントはmessages/live_activity/updateエンドポイントとレート制限を共有していますか？

デフォルトでは、messages/live_activity/updateエンドポイントのレート制限は、ワークスペースごとに、複数のエンドポイントにわたって、1時間あたり250,000リクエストです。詳細については、APIレート制限を参照してください。