Skip to content

ライブアクティビティを開始

post

/messages/live_activity/start

このエンドポイントを使用して、iOSアプリに表示されるライブアクティビティをリモートで開始します。このエンドポイントには追加の設定が必要です。

ライブアクティビティを作成した後、セグメント、接続オーディエンス、または特定のユーザーをターゲットにするPOSTリクエストを送信します。特定のユーザーは、外部ユーザーID、ユーザーエイリアス、またはその両方で識別します。Appleのライブアクティビティの詳細については、Starting and updating Live Activities with ActivityKit push notificationsを参照してください。

content-available が設定されていない場合、Appleプッシュ通知サービス(APNs)のデフォルトの優先度は10です。content-available が設定されている場合、この優先度は5です。詳細については、Appleプッシュオブジェクトを参照してください。

自動非表示の設定

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

  1. 後で再利用できる activity_id を含む /messages/live_activity/start リクエストを送信します。
  2. その activity_id とターゲット終了時間をバックエンドスケジューラーに保存します。
  3. ターゲット終了時間に、end_activitytrue に設定した /messages/live_activity/update リクエストを送信します。
  4. 同じ更新リクエストで非表示の動作を設定します。詳細については、/messages/live_activity/updateエンドポイントを参照してください。
  5. メッセージアクティビティログで送信イベントと結果イベントを確認します。

前提条件

このエンドポイントを使用するには、以下の前提条件を満たしてください。

レート制限

APIレート制限に記載されているように、このエンドポイントにはBrazeのデフォルトのレート制限(1時間あたり250,000リクエスト)が適用されます。

リクエスト本文

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "app_id": "(required, string) App API identifier retrieved from the Developer Console.",
  "activity_id": "(required, string) Define a custom string as your `activity_id`. Use this ID to send update or end events to your Live Activity.",
  "activity_attributes_type": "(required, string) The activity attributes type you define within `liveActivities.registerPushToStart` in your app.",
  "activity_attributes": "(required, object) The static attribute values for the activity type (such as the sports team names, which don't change)",
  "content_state": "(required, object) You define the ContentState parameters when you create your Live Activity. Pass the updated values for your ContentState using this object. The format of this request must match the shape you initially defined.",
  "stale_date": "(optional, datetime in ISO-8601 format) The time the Live Activity content is marked as outdated in the user’s UI.",
  "notification": "(required, object) Include an `apple_push` object to define a push notification that creates an alert for the user, displayed on paired watchOS devices. Include `notification.alert.title` and `notification.alert.body`.",
  // Include one targeting method:
  // 1. "external_user_ids", "user_aliases", or both (combined maximum 50)
  // 2. "custom_audience"
  // 3. "segment_id"
  "external_user_ids": "(optional, array of strings) see external user identifier",
  "user_aliases": "(optional, array of user alias objects) see user alias object",
  "custom_audience": "(optional, connected audience object) see connected audience",
  "segment_id": "(optional, string) see segment identifier"
}

リクエストパラメーター

パラメーター 必須 データタイプ 説明
app_id 必須 文字列 APIキーページから取得したアプリAPI識別子
activity_id 必須 文字列 カスタム文字列を activity_id として定義します。このIDは、ライブアクティビティに更新または終了イベントを送信する際に使用します。
activity_attributes_type 必須 文字列 アプリ内の liveActivities.registerPushToStart で定義するアクティビティ属性タイプ。
activity_attributes 必須 オブジェクト アクティビティタイプの静的属性値(スポーツチームの名前など、変更されないもの)。
content_state 必須 オブジェクト ライブアクティビティを作成する際に ContentState パラメーターを定義します。このオブジェクトを使用して、ContentState の更新された値を渡します。

このリクエストの形式は、最初に定義した形状と一致している必要があります。
stale_date オプション 日時
(ISO-8601 文字列)
このパラメーターは、ライブアクティビティのコンテンツがユーザーのUIで古いものとしてマークされる時間をシステムに通知します。
notification 必須 オブジェクト プッシュ通知を定義するapple_pushオブジェクトを含めます。このプッシュ通知の動作は、ユーザーがアクティブかどうか、またはユーザーがプロキシデバイスを使用しているかどうかによって異なります。
  • notification が含まれており、更新が配信されたときにユーザーがiPhoneでアクティブである場合、更新されたライブアクティビティUIがスライドダウンしてプッシュ通知のように表示されます。
  • notification が含まれており、ユーザーがiPhoneでアクティブでない場合、ロック画面に更新されたライブアクティビティUIを表示するために画面が点灯します。
  • notification alert は、標準のプッシュ通知として表示されません。さらに、ユーザーがApple Watchのようなプロキシデバイスを持っている場合、alert がそこに表示されます。
external_user_ids user_aliasessegment_id、または custom_audience が提供されている場合はオプション 文字列の配列 外部ユーザーIDを参照してください。
user_aliases external_user_idssegment_id、または custom_audience が提供されている場合はオプション ユーザーエイリアスオブジェクトの配列 ユーザーエイリアスオブジェクトを参照してください。
segment_id external_user_idsuser_aliases、または custom_audience が提供されている場合はオプション 文字列 セグメント識別子を参照してください。
custom_audience external_user_idsuser_aliases、または segment_id が提供されている場合はオプション 接続オーディエンスオブジェクト 接続オーディエンスを参照してください。

同じリクエストに external_user_idsuser_aliases を含めることができます。結合された配列の長さは50を超えることはできません。Brazeはいずれかのパラメーターに一致するユーザーをターゲットにし、複数の識別子が同じユーザーに解決される場合は1回だけ送信します。

external_user_ids または user_aliasessegment_idcustom_audience と組み合わせないでください。このエンドポイントでは、custom_audience を使用して接続オーディエンスフィルターを渡します。

リクエスト例

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
27
28
29
30
curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_activity/start' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_REST_API_KEY}' \
--data-raw '{
  "app_id": "{YOUR_APP_API_IDENTIFIER}",
  "activity_id": "football-chiefs-bills-2024-01-21",
  "content_state": {
    "teamOneScore": 0,
    "teamTwoScore": 0
  },
  "activity_attributes_type": "FootballActivity",
  "activity_attributes": {
    "team1Name": "Chiefs",
    "team2Name": "Bills"
  },
  "stale_date": "2024-01-22T16:55:49+0000",
  "notification": {
    "alert": {
      "body": "The game is starting! Tune in soon!",
      "title": "Chiefs v. Bills"
    }
  },
  "external_user_ids": ["user-id1", "user-id2"],
  "user_aliases": [
    {
      "alias_name": "user-name",
      "alias_label": "user-label"
    }
  ]
}'

レスポンス

このエンドポイントには 2014XX の2つのステータスコードレスポンスがあります。

成功レスポンスの例

リクエストが正しくフォーマットされ、Brazeが受信した場合、201 ステータスコードが返されます。ステータスコード 201 は、次のレスポンス本文を返す可能性があります。

1
2
3
{
  "message": "success"
}

エラーレスポンスの例

4XX クラスのステータスコードはクライアントエラーを示します。発生する可能性のあるエラーの詳細については、APIエラーとレスポンスの記事を参照してください。

ステータスコード 400 は、次のレスポンス本文を返す可能性があります。

1
2
3
{
    "error": "\nProblem:\n  message body does not match declared format\nResolution:\n  when specifying application/json as content-type, you must pass valid application/json in the request's 'body' "
}
New Stuff!