Skip to content

ライブアクティビティを更新する

post

/messages/live_activity/update

このエンドポイントを使用して、iOSアプリが表示するライブ・アクティビティを更新・終了する。このエンドポイントには追加の設定が必要である。

ライブ・アクティビティを登録した後、アップル・プッシュ・ノーティフィケーション・サービス(APN)をアップデートするためにJSONペイロードを渡すことができる。詳しくは、プッシュ通知ペイロードを使ったライブアクティビティの更新に関する Apple のドキュメントを参照してください。

前提条件

このエンドポイントを使用するには、以下を完了する必要がある:

  • messages.live_activity.update 権限を持つ API キーを生成する。
  • Braze Swift SDK を使用して、リモートまたはローカルでライブアクティビティを登録する。

レート制限

API レート制限で説明されているように、このエンドポイントにはデフォルトの1時間あたり25万リクエストのBraze レート 制限が適用されます。

Request body

1
2
3
4
5
6
7
8
9
{
   "app_id": "(required, string) App API identifier retrieved from the Developer Console.",
   "activity_id": "(required, string) When you register your Live Activity using launchActivity, you use the pushTokenTag parameter to name the Activity’s push token to a custom string. Set activity_id to this custom string to define which Live Activity you want to update.",
   "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.",
   "end_activity": "(optional, boolean) If true, this request ends the Live Activity.",
   "dismissal_date": "(optional, datetime in ISO-8601 format) The time to remove the Live Activity from the user’s UI. If this time is in the past, the Live Activity will be removed immediately.",
   "stale_date": "(optional, datetime in ISO-8601 format) The time the Live Activity content is marked as outdated in the user’s UI.",
   "notification": "(optional, object ) Include an `apple_push` object to define a push notification that creates an alert for the user."
 }

リクエストパラメーター

パラメーター required データ型 説明
app_id 必須 string API キーページから取得したアプリ API 識別子
activity_id 必須 string launchActivity を使用してライブアクティビティを登録する場合は、pushTokenTag パラメーターを使用して、アクティビティのプッシュトークンにカスタム文字列を名前として付けます。

activity_id をこのカスタム文字列に設定して、更新するライブアクティビティを定義します。
content_state required オブジェクト ライブアクティビティを作成する際は、ContentState パラメーターを定義します。このオブジェクトを使って、ContentState の更新値を渡す。

このリクエストのフォーマットは、最初に定義した形状と一致していなければなりません。
end_activity オプション ブール値 true の場合、このリクエストはライブアクティビティを終了します。
dismissal_date オプション 日付
(ISO-8601文字列)
このパラメーターは、ユーザーの UI からライブアクティビティを削除する時間を定義します。この時間が過去のもので、end_activitytrue の場合、ライブアクティビティは直ちに削除されます。

end_activityfalse であるか、省略された場合、このパラメーターはライブアクティビティのみを更新します。
stale_date オプション 日付
(ISO-8601文字列)
このパラメーターは、ライブアクティビティのコンテンツがユーザーの UI で古いものとしてマークされたときに、システムに通知します。
notification オプション オブジェクト プッシュ通知を定義する apple_pushオブジェクトを含める。このプッシュ通知の動作は、ユーザーがアクティブかどうか、またはユーザーがプロキシデバイスを使用しているかどうかに依存する。
  • もし notification が含まれており、アップデートが配信されたときにユーザーがiPhoneでアクティブになっていると、更新されたライブ・アクティビティUIがスライドダウンし、プッシュ通知のように表示される。
  • もし notification が含まれており、ユーザーがiPhoneをアクティブにしていない場合、画面が点灯し、ロック画面に更新されたライブ・アクティビティUIが表示される。
  • その notification alert は標準のプッシュ通知としては表示されません。さらに、ユーザーがApple Watchのようなプロキシデバイスを持っている場合は alert が表示される。

リクエスト例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_activity/update' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR-REST-API-KEY}' \
--data-raw '{
    "app_id": "{YOUR-APP-API-IDENTIFIER}",
    "activity_id": "live-activity-1",
    "content_state": {
        "teamOneScore": 2,
        "teamTwoScore": 4
    },
    "end_activity": false,
    "dismissal_date": "2023-02-28T00:00:00+0000",
    "stale_date": "2023-02-27T16:55:49+0000",
    "notification": {
        "alert": {
            "body": "It's halftime! Let's look at the scores",
            "title": "Halftime"
        }
    }
}'

応答

このエンドポイントには、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!