Skip to content

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

post

/messages/live_activity/start

このエンドポイントを使用して、iOS アプリに表示される Live Activities をリモートで開始します。このエンドポイントには追加のセットアップが必要です。

ライブアクティビティを作成した後、任意の Segment のアクティビティをリモートで開始するために POST リクエストを送信できます。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
{
  "app_id": "(required, string) App API identifier retrieved from the Developer Console.",
  "activity_id": "(required, string) Define a custom string as your `activity_id`. You will use this ID when you wish 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. Should include `notification.alert.title` and `notification.alert.body`",
  // One of the following:
  "external_user_ids": "(optional, array of strings) see external user identifier, maximum 50",
  "custom_audience": "(optional, connected audience object) see connected audience",
  "segment_id": "(optional, string) see segment identifier"
}

リクエストパラメーター

リクエスト例

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
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"
        }
    },
    // One of the following required:
    "segment_id": "{YOUR-SEGMENT-API-IDENTIFIER}", // Optional
    "custom_audience": {...}, // Optional
    "external_user_ids": ["user-id1", "user-id2"], // Optional
}'

応答

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

成功応答の例

リクエストが正しくフォーマットされ、受信された場合、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!