SWIFTのためのライブ活動

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

CDI の仕組み

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

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

シーケンス図

• ライブ活動シーケンス図

---
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>- `dismissal_date` is now in the past<br>- Setting `end_activity: true`
  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 アプリケーションにライブアクティビティをセットアップします。このタスクの一部として、YES に設定した NSSupportsLiveActivities を Info.plist に含めます。

Live Activity の正確な性質はビジネスケースに固有であるため、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メソッドをユーザー・ライフサイクルの早い段階で使用し、プッシュ・トゥ・スタート・トークンが必要になる前に、エンドポイントを使用してアクティビティを開始する。 /messages/live_activity/startエンドポイントを使用してアクティビティを開始する。
• 地元だ：Live Activity のインスタンスを作成し、launchActivity メソッドを使用して、管理するBrazeのプッシュトークンs を作成します。

• 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 を介して渡されたプッシュ通知を介してライブアクティビティを更新できます。このエンドポイントを使用して、Live Activity のContentState を更新します。

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

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

ステップ 5: 活動を終了する

ライブアクティビティが有効な場合、ユーザーのロック画面とダイナミックアイランドの両方に表示されます。ライブアクティビティを終了し、ユーザーの UI から削除する方法はいくつかあります。

• ユーザーによる却下:ユーザーは手動でライブアクティビティを削除できます。
• タイムアウト:デフォルトである8時間が経過すると、iOS はユーザーのダイナミックアイランドからライブアクティビティを削除します。デフォルトである12時間が経過すると、iOS はユーザーのロック画面からライブアクティビティを削除します。
• 却下日:タイムアウトする前に、ユーザーのユーザーインターフェイスからライブアクティビティを削除する日時を指定できます。これは、アクティビティの ActivityUIDismissalPolicy で定義するか、/messages/live_activity/update エンドポイントへのリクエストで dismissal_date パラメータを使用して定義します。
• アクティビティの終了:/messages/live_activity/update エンドポイントへのリクエストで end_activity を true に設定すると、すぐにライブアクティビティを終了できます。

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

よくある質問 (FAQ)

機能性とサポート

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

ライブアクティビティは現在、iOS 特有の機能です。ライブアクティビティの記事では、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はキャンペーンやキャンバスのステップとしてのライブ活動をサポートしているか？

いや、これは現在サポートされていない。

プッシュ通知とライブ活動

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

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

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

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

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

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

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

技術的な話題とトラブルシューティング

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

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

Push-to-start 通知を送信した後、Live Activity を受信していないのはなぜですか?

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

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

プッシュ・トゥ・スタートでライブ・アクティビティを開始したのに、なぜ新しい更新を受け取らないのか？

上記の手順が正しく実行されていることを確認する。あなたのActivityAttributes には、BrazeLiveActivityAttributes プロトコル適合性とbrazeActivityId プロパティの両方が含まれていなければならない。

Live Activityのプッシュ通知受信後、Braze URLの/push_token_tag エンドポイントへのネットワークリクエストの発信が確認でき、"tag" フィールドの下に正しいアクティビティIDが含まれていることを再確認する。

live_activity/update エンドポイントを使おうとすると、アクセス拒否応答が表示されます。なぜでしょう？

使用するAPIキーには、さまざまなBraze APIエンドポイントにアクセスするための適切なパーミッションを与える必要がある。以前に作成したAPIキーを使用している場合、その権限の更新を怠っている可能性がある。API キーセキュリティの概要を読んで再確認してください。

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

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