From 18a89e36f08df18e2ff6ad0e315b0f0ea981202b Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Fri, 24 Feb 2023 14:44:05 -0500 Subject: [PATCH 01/26] WIP --- .../endpoints/messaging/live_activities.md | 4 + .../messaging/live_activities/update.md | 79 +++++++++++++++++++ .../post_send_transactional_message.md | 2 +- .../swift/live_activities.md | 27 +++++++ 4 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 _docs/_api/endpoints/messaging/live_activities.md create mode 100644 _docs/_api/endpoints/messaging/live_activities/update.md create mode 100644 _docs/_developer_guide/platform_integration_guides/swift/live_activities.md diff --git a/_docs/_api/endpoints/messaging/live_activities.md b/_docs/_api/endpoints/messaging/live_activities.md new file mode 100644 index 00000000000..e77b5f2ee82 --- /dev/null +++ b/_docs/_api/endpoints/messaging/live_activities.md @@ -0,0 +1,4 @@ +--- +nav_title: Live Activities +config_only: true +--- diff --git a/_docs/_api/endpoints/messaging/live_activities/update.md b/_docs/_api/endpoints/messaging/live_activities/update.md new file mode 100644 index 00000000000..67310d93b22 --- /dev/null +++ b/_docs/_api/endpoints/messaging/live_activities/update.md @@ -0,0 +1,79 @@ +--- +nav_title: "POST: Update Live Activity" +article_title: "POST: Update Live Activity" +search_tag: Endpoint +page_order: 1 + +layout: api_page +page_type: reference +description: "This article outlines details about the Update Live Activity endpoint." + +--- +{% api %} +# Update Live Activity +{% apimethod post %} +/messages/live_activity/update +{% endapimethod %} + +Use this endpoint to LOREM IPSUM IPSUM LOREM. + +## Rate limit + + + +{% multi_lang_include rate_limits.md endpoint='default' category='message endpoints' %} + +## Request parameters + +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `app_id` | Required | apiKey | The API key for the app displaying the live activity must be included in your request. | +| `activity_id` | Required | string | Lorem ipsum. | +| `content_state` | Required | object | Lorem ipsum. | +| `end_activity` | Optional | boolean | Lorem ipsum. | +| `dismissal_date` | Optional | string in ISO 8601 format | Lorem ipsum. | +| `stale_date` | Optional | string in ISO 8601 format | Lorem ipsum. | +| `notification` | Optional | Apple push object | Lorem ipsum. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} + +## Example Request + +```javascript +curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer {YOUR-REST-API-KEY}' \ +--data-raw '{ + "app_id": (required, App API Key), + "activity_id": (required, string), + "content_state": (required, object) - shape should match the integrator’s app’s custom live activity integration, + "end_activity": (optional, boolean) - if specified, end this activity for recipients, + "dismissal_date": (optional, ISO 8601 date string) - if supplied, a custom time to remove the activity from the user's UI - if in the past, will remove immediately. + "stale_date": (optional, ISO 8601 date string) - if supplied, a time to mark this update as outdated in the user's UI, + "notification": (optional, Apple Push Object) - if supplied, a notification to display along with this update +} + +``` + +## Response + +There are three status code responses for this endpoint: `201`, `400`, and `404`. + +### Example success response + +The status code `201` could return the following response body. + +```json +{ + "message": "success" +} +``` + +### Example error response + +The status code `400` could return the following response body. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. + +```json + +``` + +{% endapi %} \ No newline at end of file diff --git a/_docs/_api/endpoints/messaging/send_messages/post_send_transactional_message.md b/_docs/_api/endpoints/messaging/send_messages/post_send_transactional_message.md index a351cfbfa71..f258c73f04e 100644 --- a/_docs/_api/endpoints/messaging/send_messages/post_send_transactional_message.md +++ b/_docs/_api/endpoints/messaging/send_messages/post_send_transactional_message.md @@ -110,7 +110,7 @@ The endpoint may also return an error code and a human-readable message in some Most endpoints at Braze have a rate limit implementation that will return a 429 response code if you have made too many requests. The transactional sending endpoint works differently -- if you exceed your allotted rate limit, our system will continue to ingest the API calls, return success codes, and send the messages, however those messages may not be subject to the contractual SLA for the feature. Please reach out if you need more information about this functionality. - ### Transactional HTTP event postback +### Transactional HTTP event postback All transactional emails are complemented with event status postbacks sent as an HTTP request back to your specified URL. This will allow you to evaluate the message status in real-time and take action to reach the user on another channel if the message goes undelivered, or fallback to an internal system if Braze is experiencing latency. diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md new file mode 100644 index 00000000000..829dde6df91 --- /dev/null +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -0,0 +1,27 @@ +--- +hidden: true +nav_title: Live Activities +article_title: Live Activities for iOS +platform: Swift +page_order: 8 +description: "This article covers using Braze to manage your Live Activities tokens." + +--- + +# Live Activities for iOS + +Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real time. + +As a developer, you can use the Braze Swift SDK to easily manage Live Activity push tokens. Then, you can use the Braze REST API to send Live Activity updates, and have all subscribed devices receive the update as quickly as possible. + +## Prerequisites + +## Integrating Live Activities with the Braze Swift SDK + +## Registering a Live Activity + +### Example + +## Updating a Live Activity + +### Example \ No newline at end of file From deb440703ba74614dbe89de3968d953dd650221b Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Fri, 24 Feb 2023 19:07:31 -0500 Subject: [PATCH 02/26] End of day commit --- .../endpoints/messaging/live_activities.md | 4 - .../messaging/live_activities/update.md | 79 -------- .../_api/endpoints/messaging/live_activity.md | 4 + .../messaging/live_activity/update.md | 93 ++++++++++ .../swift/live_activities.md | 169 +++++++++++++++++- 5 files changed, 260 insertions(+), 89 deletions(-) delete mode 100644 _docs/_api/endpoints/messaging/live_activities.md delete mode 100644 _docs/_api/endpoints/messaging/live_activities/update.md create mode 100644 _docs/_api/endpoints/messaging/live_activity.md create mode 100644 _docs/_api/endpoints/messaging/live_activity/update.md diff --git a/_docs/_api/endpoints/messaging/live_activities.md b/_docs/_api/endpoints/messaging/live_activities.md deleted file mode 100644 index e77b5f2ee82..00000000000 --- a/_docs/_api/endpoints/messaging/live_activities.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -nav_title: Live Activities -config_only: true ---- diff --git a/_docs/_api/endpoints/messaging/live_activities/update.md b/_docs/_api/endpoints/messaging/live_activities/update.md deleted file mode 100644 index 67310d93b22..00000000000 --- a/_docs/_api/endpoints/messaging/live_activities/update.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -nav_title: "POST: Update Live Activity" -article_title: "POST: Update Live Activity" -search_tag: Endpoint -page_order: 1 - -layout: api_page -page_type: reference -description: "This article outlines details about the Update Live Activity endpoint." - ---- -{% api %} -# Update Live Activity -{% apimethod post %} -/messages/live_activity/update -{% endapimethod %} - -Use this endpoint to LOREM IPSUM IPSUM LOREM. - -## Rate limit - - - -{% multi_lang_include rate_limits.md endpoint='default' category='message endpoints' %} - -## Request parameters - -| Parameter | Required | Data Type | Description | -|---|---|---|---| -| `app_id` | Required | apiKey | The API key for the app displaying the live activity must be included in your request. | -| `activity_id` | Required | string | Lorem ipsum. | -| `content_state` | Required | object | Lorem ipsum. | -| `end_activity` | Optional | boolean | Lorem ipsum. | -| `dismissal_date` | Optional | string in ISO 8601 format | Lorem ipsum. | -| `stale_date` | Optional | string in ISO 8601 format | Lorem ipsum. | -| `notification` | Optional | Apple push object | Lorem ipsum. | -{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} - -## Example Request - -```javascript -curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer {YOUR-REST-API-KEY}' \ ---data-raw '{ - "app_id": (required, App API Key), - "activity_id": (required, string), - "content_state": (required, object) - shape should match the integrator’s app’s custom live activity integration, - "end_activity": (optional, boolean) - if specified, end this activity for recipients, - "dismissal_date": (optional, ISO 8601 date string) - if supplied, a custom time to remove the activity from the user's UI - if in the past, will remove immediately. - "stale_date": (optional, ISO 8601 date string) - if supplied, a time to mark this update as outdated in the user's UI, - "notification": (optional, Apple Push Object) - if supplied, a notification to display along with this update -} - -``` - -## Response - -There are three status code responses for this endpoint: `201`, `400`, and `404`. - -### Example success response - -The status code `201` could return the following response body. - -```json -{ - "message": "success" -} -``` - -### Example error response - -The status code `400` could return the following response body. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. - -```json - -``` - -{% endapi %} \ No newline at end of file diff --git a/_docs/_api/endpoints/messaging/live_activity.md b/_docs/_api/endpoints/messaging/live_activity.md new file mode 100644 index 00000000000..f68507b46b5 --- /dev/null +++ b/_docs/_api/endpoints/messaging/live_activity.md @@ -0,0 +1,4 @@ +--- +nav_title: Live Activity +config_only: true +--- diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md new file mode 100644 index 00000000000..9e1446e1e22 --- /dev/null +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -0,0 +1,93 @@ +--- +nav_title: "POST: Update Live Activity" +article_title: "POST: Update Live Activity" +search_tag: Endpoint +page_order: 1 + +layout: api_page +page_type: reference +description: "This article outlines details about the Update Live Activity endpoint." + +--- +{% api %} +# Update Live Activity +{% apimethod post %} +/messages/live_activity/update +{% endapimethod %} + +Use this endpoint to handle updates for Live Activities displayed by your iOS app. + +Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. See the [Live Activities article]({{site.baseurl}}/docs/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. + +## Rate limit + + + +{% multi_lang_include rate_limits.md endpoint='default' category='message endpoints' %} + +## Request parameters + +| Parameter | Required | Data Type | Description | +|---|---|---|---| +| `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-identifier) retrieved from the **Developer Console**. | +| `activity_id` | Required | String | Lorem ipsum. | +| `content_state` | Required | Object | Lorem ipsum. | +| `end_activity` | Optional | Boolean | If `true`, this request ends the Live Activity. | +| `dismissal_date` | Optional | Datetime
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines 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
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. | +| `notification` | Optional | Object | Include an [`apple_push`]({{site.baseurl}}/api/objects_filters/messaging/apple_object/) object to define a push notification that will also be displayed with this update. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} + +## Example Request + +```javascript +curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer {YOUR-REST-API-KEY}' \ +--data-raw '{ + "app_id": "{YOUR-APP-API-IDENTIFIER}", + "activity_id": "lorem ipsum", + "content_state": "lorem ipsum", + "end_activity": false, + "dismissal_date": "lorem ipsum", + "stale_date": "lorem ipsum", + "notification": { + "apple_push": { + "alert": "Halftime!", + "badge": 1 + } + } +} +``` + +## Response + + + +There are XX status code responses for this endpoint: `201`, XX, and XX. + +### Response parameters + + + +### Example success response + +The status code `201` could return the following response body. + +```json +{ + "message": "success" +} +``` + +### Example error response + +The status code `400` could return the following response body. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. + + + +```json + +``` + +{% endapi %} \ No newline at end of file diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 829dde6df91..9a87d5203b3 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -10,18 +10,175 @@ description: "This article covers using Braze to manage your Live Activities tok # Live Activities for iOS -Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real time. +{% alert important %} +Live Activities are currently in early access. Contact your Braze account manager if you're interested in participating in the early access. +{% endalert %} -As a developer, you can use the Braze Swift SDK to easily manage Live Activity push tokens. Then, you can use the Braze REST API to send Live Activity updates, and have all subscribed devices receive the update as quickly as possible. +Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real time. Because they appear on the lock screen, Live Activities ensure that your notifications won't be missed. Because they're persistent, you can display up-to-date content to your users without even having them unlock their phone. + +As a developer, you can use the Braze Swift SDK to easily manage Live Activity push tokens. You can use the Braze REST API to make Live Activity updates, and have all subscribed devices receive the update as quickly as possible. And, because you're managing Live Activities through Braze, you can use them in tandem with your other messaging channels—push notifications, in-app messages, Content Cards—to drive adoption. ## Prerequisites -## Integrating Live Activities with the Braze Swift SDK +Live Activities are only available for iPhones on iOS 16.1 and later. To use this feature, ensure that your project is targeting this iOS version. + + + +{% sdk_min_versions swift:5.11.0 %} + +## Implementing a Live Activity + +To manage the lifecycle of a Live Activity, follow these four steps. + + + +1. [Create the Live Activity.] Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for static and dynamic states. + +2. [Register the Live Activity] Register a Live Activity with the Braze SDK using the `launchActivity` method with the Live Activity object and unique activity tag. + +3. [Update the Live Activity] Publish activity content updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. + +4. [End the Live Activity] End a Live Activity for all recipients by publishing an update to `/messages/live_activity/update` with the parameter `"end_activity": true`. + +## Step 1: Developing your Live Activity + + + +First, ensure that you have followed [Displaying live data with Live Activities][3] in Apple’s documentation to set up Live Activities in your iOS application. + +Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize these objects. Importantly, you will define: +* `ActivityAttributes`: This defines the static data at startup, that is, data that won’t change. +* `Activity.ContentState`: This defines the dynamic data that will be updated over the course of the activity. +* `ActivityContent`: An object that encapsulates the Live Activity's structure and additional configuration information. + +You will also use SwiftUI to create the UI presentation of the lock screen. + +Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. + +### Example + +For this example, we have created a struct called `BrazeActivityAttributes`, but you may use your own implementation of [`ActivityAttributes`][4]. + +```swift +#if canImport(ActivityKit) + import ActivityKit +#endif + +@available(iOS 16.1, *) +struct BrazeActivityAttributes: ActivityAttributes { + public struct ContentState: Codable, Hashable { + var teamOneScore: String + var teamTwoScore: String + } + + var gameName: String + var gameLocation: String +} +``` + +## Step 2: Registering a Live Activity + + + +Next, you will use Braze methods to track and manage your Live Activities. -## Registering a Live Activity +Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. You will use ActivityKit to get a push token, which the Braze SDK can manage for you. + +1. Create an instance of your Live Activity implementation using Apple’s ActivityKit APIs. +2. Pass in the Live Activities `ActivitiesAttributes` and `ContentState` you defined. +3. Register your activity with your Braze instance by passing it into [`launchActivity(pushTokenTag:activity:)`][5]. The `pushTokenTag` parameter is a custom string you define. It should be unique for each Live Activity you create. + +Once you have registered the Live Activity, the Braze SDK will extract and observe changes in the push tokens. + + +It’ll be important to call out to customers that send frequent updates to update their app’s Info.plist settings in `Determine the update frequency` ### Example -## Updating a Live Activity +For our example, we’ll create class called LiveActivityManager as an interface for our Live Activity objects. Then, we'll set the `pushTokenTag` to `"live-activity-1"`. + +```swift +import BrazeKit + +#if canImport(ActivityKit) + import ActivityKit +#endif + +class LiveActivityManager { + + @available(iOS 16.2, *) + func createActivity() { + let activityAttributes = BrazeActivityAttributes(gameName: "Superb Owl LVII", gameLocation: "Glendale, Arizona") + let contentState = BrazeActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0") + let activityContent = ActivityContent(state: contentState, staleDate: nil) + if let activity = try? Activity.request(attributes: activityAttributes, + content: activityContent) { + // Register your Live Activity with Braze using the pushTokenTag + AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "live-activity-1", + activity: activity) + } + } + +} +``` + +### Resuming Live Activity tracking + +You will need to ensure that Braze tracks your Live Activity upon app launch. + +To do this: +1. Open your `AppDelegate` file. +2. Import the `ActivityKit` module if it’s available. +3. Call [`resumeActivities(ofType:)`][6] in `application(_:didFinishLaunchingWithOptions:)` for all `ActivityAttributes` types you have registered in your application. + +This allows Braze to resume tasks to track push token updates for all active Live Activities. + +#### Example + +```swift +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.self + ) + } + + return true + } +} +``` + +## Step 3: Updating a Live Activity + +We offer the `/messages/live_activity/update` endpoint as an easy way to manage the push tokens of a Live Activity. Use this endpoint to pass changes to your `ActivitiesAttributes` and `ContentState` as you want to update your Live Activity. + +See the [`/messages/live_activity/update`][1] endpoint documentation for full details. + +### Example + +## Step 4: Ending a Live Activity + + -### Example \ No newline at end of file +[1]: {{site.baseurl}}/api/endpoints/messaging/live_activity/update +[2]: https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities#Understand-constraints +[3]: https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities +[4]: https://developer.apple.com/documentation/activitykit/activityattributes +[5]: braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/ +[6]: braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/resumeactivities(oftype:) \ No newline at end of file From 616b491299b188277c92b684ff08ae1e60764c85 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Mon, 27 Feb 2023 10:43:42 -0500 Subject: [PATCH 03/26] Apply suggestions from code review Co-authored-by: Jeriel Ng --- .../platform_integration_guides/swift/live_activities.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 9a87d5203b3..41fc0912e6e 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -51,7 +51,7 @@ Because the exact nature of your Live Activity will be specific to your business * `Activity.ContentState`: This defines the dynamic data that will be updated over the course of the activity. * `ActivityContent`: An object that encapsulates the Live Activity's structure and additional configuration information. -You will also use SwiftUI to create the UI presentation of the lock screen. +You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices. Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. @@ -67,8 +67,8 @@ For this example, we have created a struct called `BrazeActivityAttributes`, but @available(iOS 16.1, *) struct BrazeActivityAttributes: ActivityAttributes { public struct ContentState: Codable, Hashable { - var teamOneScore: String - var teamTwoScore: String + var teamOneScore: Int + var teamTwoScore: Int } var gameName: String @@ -112,7 +112,8 @@ class LiveActivityManager { let contentState = BrazeActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0") let activityContent = ActivityContent(state: contentState, staleDate: nil) if let activity = try? Activity.request(attributes: activityAttributes, - content: activityContent) { + content: activityContent, + pushType: .token) { // Register your Live Activity with Braze using the pushTokenTag AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "live-activity-1", activity: activity) From 5ca2d258d8731f2e038d56dc8969c4128e0813a1 Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Mon, 27 Feb 2023 11:57:48 -0500 Subject: [PATCH 04/26] Updated endpoint example --- .../messaging/live_activity/update.md | 32 +++++++++++-------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 9e1446e1e22..9d39bfe158c 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -1,4 +1,5 @@ --- +hidden: true nav_title: "POST: Update Live Activity" article_title: "POST: Update Live Activity" search_tag: Endpoint @@ -40,23 +41,28 @@ Before using this endpoint, you must register an activity with the Braze Swift S ## Example Request + + ```javascript -curl --location --request POST 'https://rest.iad-03.braze.com/catalogs/restaurants/items/restaurant1' \ +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": "lorem ipsum", - "content_state": "lorem ipsum", - "end_activity": false, - "dismissal_date": "lorem ipsum", - "stale_date": "lorem ipsum", - "notification": { - "apple_push": { - "alert": "Halftime!", - "badge": 1 + "app_id": "{YOUR-APP-API-IDENTIFIER}", + "activity_id": "halftimeScore", + "content_state": { + "team1Score": 2, + "team2Score": 4 + }, + "end_activity": false, + "dismissal_date": "2023-02-28T00:00:00+0000", + "stale_date": "2023-02-27T16:55:49+0000", + "notification": { + "apple_push": { + "alert": "Halftime!", + "badge": 1 + } } - } } ``` @@ -68,7 +74,7 @@ There are XX status code responses for this endpoint: `201`, XX, and XX. ### Response parameters - + ### Example success response From 8d866c37e9b292ff734df025581821acfa7dbe26 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Mon, 27 Feb 2023 14:11:14 -0500 Subject: [PATCH 05/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: Jeriel Ng --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 41fc0912e6e..e05ac9997aa 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -91,7 +91,7 @@ Updates to a Live Activity can be sent using ActivityKit (Apple’s framework fo Once you have registered the Live Activity, the Braze SDK will extract and observe changes in the push tokens. -It’ll be important to call out to customers that send frequent updates to update their app’s Info.plist settings in `Determine the update frequency` +Note: If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by the APNs budget limit by adding setting `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your Info.plist file. For more details, refer to the `[Determine the update frequency](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency)` section in the ActivityKit documentation. ### Example From 6e928042d1a883b3124c2df34712c9a019c87e7a Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Mon, 27 Feb 2023 14:11:34 -0500 Subject: [PATCH 06/26] WIP --- .../swift/live_activities.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 41fc0912e6e..f32dbc174f2 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -16,34 +16,34 @@ Live Activities are currently in early access. Contact your Braze account manage Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real time. Because they appear on the lock screen, Live Activities ensure that your notifications won't be missed. Because they're persistent, you can display up-to-date content to your users without even having them unlock their phone. -As a developer, you can use the Braze Swift SDK to easily manage Live Activity push tokens. You can use the Braze REST API to make Live Activity updates, and have all subscribed devices receive the update as quickly as possible. And, because you're managing Live Activities through Braze, you can use them in tandem with your other messaging channels—push notifications, in-app messages, Content Cards—to drive adoption. +As a developer, you can use Braze to manage your Live Activity lifecycles. Make calls to the Braze REST API to make Live Activity updates and have all subscribed devices receive the update as quickly as possible. And, because you're managing Live Activities through Braze, you can use them in tandem with your other messaging channels—push notifications, in-app messages, Content Cards—to drive adoption. ## Prerequisites -Live Activities are only available for iPhones on iOS 16.1 and later. To use this feature, ensure that your project is targeting this iOS version. - {% sdk_min_versions swift:5.11.0 %} +Additional prerequisites include: +* Live Activities are only available for iPhones on iOS 16.1 and later. To use this feature, ensure that your project is targeting this iOS version. +* The `Push Notification` entitlement must be added under Signing & Capabilities in your Xcode project. + ## Implementing a Live Activity To manage the lifecycle of a Live Activity, follow these four steps. -1. [Create the Live Activity.] Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for static and dynamic states. +1. [Create the Live Activity.] Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states. 2. [Register the Live Activity] Register a Live Activity with the Braze SDK using the `launchActivity` method with the Live Activity object and unique activity tag. -3. [Update the Live Activity] Publish activity content updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. +3. [Update the Live Activity] Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. 4. [End the Live Activity] End a Live Activity for all recipients by publishing an update to `/messages/live_activity/update` with the parameter `"end_activity": true`. ## Step 1: Developing your Live Activity - - First, ensure that you have followed [Displaying live data with Live Activities][3] in Apple’s documentation to set up Live Activities in your iOS application. Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize these objects. Importantly, you will define: @@ -51,10 +51,16 @@ Because the exact nature of your Live Activity will be specific to your business * `Activity.ContentState`: This defines the dynamic data that will be updated over the course of the activity. * `ActivityContent`: An object that encapsulates the Live Activity's structure and additional configuration information. -You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices. +You will also use SwiftUI to create the UI presentation of the lock screen. Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. +### Frequently updated Live Activities +To prevent spam, Apple normally rate limits + + +It’ll be important to call out to customers that send frequent updates to update their app’s Info.plist settings in `Determine the update frequency` + ### Example For this example, we have created a struct called `BrazeActivityAttributes`, but you may use your own implementation of [`ActivityAttributes`][4]. @@ -78,8 +84,6 @@ struct BrazeActivityAttributes: ActivityAttributes { ## Step 2: Registering a Live Activity - - Next, you will use Braze methods to track and manage your Live Activities. Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. You will use ActivityKit to get a push token, which the Braze SDK can manage for you. @@ -90,9 +94,6 @@ Updates to a Live Activity can be sent using ActivityKit (Apple’s framework fo Once you have registered the Live Activity, the Braze SDK will extract and observe changes in the push tokens. - -It’ll be important to call out to customers that send frequent updates to update their app’s Info.plist settings in `Determine the update frequency` - ### Example For our example, we’ll create class called LiveActivityManager as an interface for our Live Activity objects. Then, we'll set the `pushTokenTag` to `"live-activity-1"`. @@ -112,8 +113,7 @@ class LiveActivityManager { let contentState = BrazeActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0") let activityContent = ActivityContent(state: contentState, staleDate: nil) if let activity = try? Activity.request(attributes: activityAttributes, - content: activityContent, - pushType: .token) { + content: activityContent) { // Register your Live Activity with Braze using the pushTokenTag AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "live-activity-1", activity: activity) From 8ee092869dc3d26ded2075e4522ae66356c4b98c Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Mon, 27 Feb 2023 16:53:10 -0500 Subject: [PATCH 07/26] End of day update --- .../messaging/live_activity/update.md | 12 ++-- .../swift/live_activities.md | 63 ++++++++++--------- .../push_notifications/safari_mobile_push.md | 14 ++--- 3 files changed, 46 insertions(+), 43 deletions(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 9d39bfe158c..042f0d0ab8c 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -28,11 +28,13 @@ Before using this endpoint, you must register an activity with the Braze Swift S ## Request parameters + + | Parameter | Required | Data Type | Description | |---|---|---|---| | `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-identifier) retrieved from the **Developer Console**. | -| `activity_id` | Required | String | Lorem ipsum. | -| `content_state` | Required | Object | Lorem ipsum. | +| `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
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines 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
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. | @@ -49,10 +51,10 @@ curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_acti --header 'Authorization: Bearer {YOUR-REST-API-KEY}' \ --data-raw '{ "app_id": "{YOUR-APP-API-IDENTIFIER}", - "activity_id": "halftimeScore", + "activity_id": "live-activity-1", "content_state": { - "team1Score": 2, - "team2Score": 4 + "teamOneScore": 2, + "teamTwoScore": 4 }, "end_activity": false, "dismissal_date": "2023-02-28T00:00:00+0000", diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index af53de98556..fa1a3a92e02 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -32,38 +32,34 @@ Additional prerequisites include: To manage the lifecycle of a Live Activity, follow these four steps. - +1. [Create the Live Activity.](#developing) Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states. -1. [Create the Live Activity.] Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states. +2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the `launchActivity` method with the Live Activity object and unique activity tag. -2. [Register the Live Activity] Register a Live Activity with the Braze SDK using the `launchActivity` method with the Live Activity object and unique activity tag. +3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. -3. [Update the Live Activity] Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. +4. [End the Live Activity](#ending) End a Live Activity for all recipients by publishing an update to `/messages/live_activity/update` with the parameter `"end_activity": true`. -4. [End the Live Activity] End a Live Activity for all recipients by publishing an update to `/messages/live_activity/update` with the parameter `"end_activity": true`. +## Step 1: Developing your Live Activity {#developing} -## Step 1: Developing your Live Activity +First, ensure that you have followed [Displaying live data with Live Activities][3] in Apple’s documentation to set up Live Activities in your iOS application. As part of this task, make sure you include `NSSupportsLiveActivities` set to `YES` in your `Info.plist`. -First, ensure that you have followed [Displaying live data with Live Activities][3] in Apple’s documentation to set up Live Activities in your iOS application. +Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize the [Activity][4] objects. Importantly, you will define: +* `ActivityAttributes`: This protocol defines the static (unchanging) and dynamic (changing) content that will appear in your Live Activity. +* `Activity.ContentState`: This type defines the dynamic data that will be updated over the course of the activity. +* `ActivityContent`: A structure that encapsulates the Live Activity's structure and additional configuration information. -Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize these objects. Importantly, you will define: -* `ActivityAttributes`: This defines the static data at startup, that is, data that won’t change. -* `Activity.ContentState`: This defines the dynamic data that will be updated over the course of the activity. -* `ActivityContent`: An object that encapsulates the Live Activity's structure and additional configuration information. - -You will also use SwiftUI to create the UI presentation of the lock screen. +You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices. Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. -### Frequently updated Live Activities -To prevent spam, Apple normally rate limits - - -It’ll be important to call out to customers that send frequent updates to update their app’s Info.plist settings in `Determine the update frequency` +{% alert note %} +If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by Apple's budget limit by adding `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your `Info.plist` file. For more details, refer to the `[Determine the update frequency`](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency) section in the ActivityKit documentation. +{% endalert %} ### Example -For this example, we have created a struct called `BrazeActivityAttributes`, but you may use your own implementation of [`ActivityAttributes`][4]. +Let's imagine that we want to create a Live Activity to give our users updates for the Superb Owl show, where two competing wildlife rescues are given points for the owls they have in residence. For this example, we have created a struct called `BrazeActivityAttributes`, but you may use your own implementation of `ActivityAttributes`. ```swift #if canImport(ActivityKit) @@ -82,21 +78,19 @@ struct BrazeActivityAttributes: ActivityAttributes { } ``` -## Step 2: Registering a Live Activity +## Step 2: Registering a Live Activity {#registering} Next, you will use Braze methods to track and manage your Live Activities. -Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. You will use ActivityKit to get a push token, which the Braze SDK can manage for you. +Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. In this instance, you will use ActivityKit to get a push token, which the Braze SDK can manage for you. This allows you to update Live Activities through the Braze API. 1. Create an instance of your Live Activity implementation using Apple’s ActivityKit APIs. -2. Pass in the Live Activities `ActivitiesAttributes` and `ContentState` you defined. -3. Register your activity with your Braze instance by passing it into [`launchActivity(pushTokenTag:activity:)`][5]. The `pushTokenTag` parameter is a custom string you define. It should be unique for each Live Activity you create. +2. Set the `pushType` parameter as `.token`. +3. Pass in the Live Activities `ActivitiesAttributes` and `ContentState` you defined. +4. Register your activity with your Braze instance by passing it into [`launchActivity(pushTokenTag:activity:)`][5]. The `pushTokenTag` parameter is a custom string you define. It should be unique for each Live Activity you create. Once you have registered the Live Activity, the Braze SDK will extract and observe changes in the push tokens. - -Note: If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by the APNs budget limit by adding setting `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your Info.plist file. For more details, refer to the `[Determine the update frequency](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency)` section in the ActivityKit documentation. - ### Example For our example, we’ll create class called LiveActivityManager as an interface for our Live Activity objects. Then, we'll set the `pushTokenTag` to `"live-activity-1"`. @@ -116,7 +110,9 @@ class LiveActivityManager { let contentState = BrazeActivityAttributes.ContentState(teamOneScore: "0", teamTwoScore: "0") let activityContent = ActivityContent(state: contentState, staleDate: nil) if let activity = try? Activity.request(attributes: activityAttributes, - content: activityContent) { + 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 AppDelegate.braze?.liveActivities.launchActivity(pushTokenTag: "live-activity-1", activity: activity) @@ -168,17 +164,22 @@ class AppDelegate: UIResponder, UIApplicationDelegate { } ``` -## Step 3: Updating a Live Activity +## Step 3: Updating a Live Activity {#updating} -We offer the `/messages/live_activity/update` endpoint as an easy way to manage the push tokens of a Live Activity. Use this endpoint to pass changes to your `ActivitiesAttributes` and `ContentState` as you want to update your Live Activity. +The `/messages/live_activity/update` endpoint allows you to update a Live Activity through push notifications passed through the Braze REST API. Use this endpoint to update your Live Activity's `ContentState`. See the [`/messages/live_activity/update`][1] endpoint documentation for full details. -### Example +## Step 4: Ending a Live Activity {#ending} -## Step 4: Ending a Live Activity +When a Live Activity is active, it is shown on both a user's lock screen and Dynamic Island. +There are a few different ways for a Live Activity to end and be removed from a user's UI. +* **Time out**: After a default time of 8 hours, iOS will remove the Live Activity from the user's Dynamic Island. After a default time of 12 hours, iOS will remove the Live Activity from the user's lock screen. +* **Dismissal date**: You can provide a datetime for a Live Activity to be removed from a user's UI prior to time out. This is defined either in the Activity's `ActivityUIDismissalPolicy` or using the `dismissal_date` parameter in requests to the `/messages/live_activity/update` endpoint. +* **End activity**: You can set `end_activity` to `true` in a request to the `/messages/live_activity/update` endpoint to immediately end a Live Activity. +See the [`/messages/live_activity/update`][1] endpoint documentation for full details. [1]: {{site.baseurl}}/api/endpoints/messaging/live_activity/update [2]: https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities#Understand-constraints diff --git a/_docs/_developer_guide/platform_integration_guides/web/push_notifications/safari_mobile_push.md b/_docs/_developer_guide/platform_integration_guides/web/push_notifications/safari_mobile_push.md index 360dcfff847..a7a895e691b 100644 --- a/_docs/_developer_guide/platform_integration_guides/web/push_notifications/safari_mobile_push.md +++ b/_docs/_developer_guide/platform_integration_guides/web/push_notifications/safari_mobile_push.md @@ -19,7 +19,7 @@ This article will guide you through the steps required to set up mobile push for First, please read and follow our standard [web push integration guide][web-push-integration]. The following steps are only required to support web push on Safari for iOS and iPadOS support. -### Step 1: Create a Mmanifest file {#manifest} +### Step 1: Create a manifest file {#manifest} A [Web Application Manifest][manifest-file] is a JSON file that controls how your website is presented when installed to a user's home screen. @@ -53,19 +53,19 @@ Add the following `` tag to your website's `` element pointing to wh Your website must have a service worker file that imports the Braze service-worker library, as described in our [web push integration guide][service-worker]. -### Step 4: Add to homescreen {#add-to-homescreen} +### Step 4: Add to home screen {#add-to-homescreen} -Unlike major browsers like Chrome and Firefox, you are not allowed to request push permission on Safari iOS/iPadOS unless your website has been added to the user's homescreen. +Unlike major browsers like Chrome and Firefox, you are not allowed to request push permission on Safari iOS/iPadOS unless your website has been added to the user's home screen. -The [Add to Homescreen][add-to-homescreen] feature lets users bookmark your website, adding your icon to their valuable homescreen real estate. +The [Add to Homescreen][add-to-homescreen] feature lets users bookmark your website, adding your icon to their valuable home screen real estate. -![An iphone showing options to bookmark a website and save to the homescreen][add-to-homescreen-img]{: style="max-width:40%"} +![An iphone showing options to bookmark a website and save to the home screen][add-to-homescreen-img]{: style="max-width:40%"} ### Step 5: Show the native push prompt {#push-prompt} -Once the app has been added to your homescreen you can now request push permission when the user takes an action (such as clicking a button). This can be done using the [`requestPushPermission`][requestPushPermission] method, or with a [no-code push primer in-app message][push-primer]. +Once the app has been added to your home screen you can now request push permission when the user takes an action (such as clicking a button). This can be done using the [`requestPushPermission`][requestPushPermission] method, or with a [no-code push primer in-app message][push-primer]. {% alert note %} -Once you accept or decline the prompt, you'll need to delete and reinstall the website to your homescreen to be able to show the prompt again. +Once you accept or decline the prompt, you'll need to delete and reinstall the website to your home screen to be able to show the prompt again. {% endalert %} ![A push prompt asking to "allow" or "don't allow" Notifications][safari-push-prompt-img]{: style="max-width:40%"} From de00ef87548477de35830822294abc3771e5502f Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Mon, 27 Feb 2023 17:23:49 -0500 Subject: [PATCH 08/26] Fixing broken links --- .../endpoints/messaging/live_activity/update.md | 6 +++--- .../swift/live_activities.md | 13 ++++++------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 042f0d0ab8c..be03b04240f 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -18,7 +18,7 @@ description: "This article outlines details about the Update Live Activity endpo Use this endpoint to handle updates for Live Activities displayed by your iOS app. -Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. See the [Live Activities article]({{site.baseurl}}/docs/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. +Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. See the [Live Activities article]({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. ## Rate limit @@ -33,7 +33,7 @@ Before using this endpoint, you must register an activity with the Braze Swift S | Parameter | Required | Data Type | Description | |---|---|---|---| | `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-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. | +| `activity_id` | Required | String | When you register your Live Activity using [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class), 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
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines 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. | @@ -45,7 +45,7 @@ Before using this endpoint, you must register an activity with the Braze Swift S -```javascript +```json 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}' \ diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index fa1a3a92e02..4cc3d5a2fd5 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -11,7 +11,7 @@ description: "This article covers using Braze to manage your Live Activities tok # Live Activities for iOS {% alert important %} -Live Activities are currently in early access. Contact your Braze account manager if you're interested in participating in the early access. +Live Activities are currently in early access. Contact your Braze account manager if you're interested in participating. {% endalert %} Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real time. Because they appear on the lock screen, Live Activities ensure that your notifications won't be missed. Because they're persistent, you can display up-to-date content to your users without even having them unlock their phone. @@ -54,7 +54,7 @@ You will also use SwiftUI to create the UI presentation of the lock screen and D Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. {% alert note %} -If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by Apple's budget limit by adding `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your `Info.plist` file. For more details, refer to the `[Determine the update frequency`](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency) section in the ActivityKit documentation. +If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by Apple's budget limit by adding `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your `Info.plist` file. For more details, refer to the [`Determine the update frequency`](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency) section in the ActivityKit documentation. {% endalert %} ### Example @@ -166,15 +166,14 @@ class AppDelegate: UIResponder, UIApplicationDelegate { ## Step 3: Updating a Live Activity {#updating} -The `/messages/live_activity/update` endpoint allows you to update a Live Activity through push notifications passed through the Braze REST API. Use this endpoint to update your Live Activity's `ContentState`. +The [`/messages/live_activity/update`][1] endpoint allows you to update a Live Activity through push notifications passed through the Braze REST API. Use this endpoint to update your Live Activity's `ContentState`. See the [`/messages/live_activity/update`][1] endpoint documentation for full details. ## Step 4: Ending a Live Activity {#ending} -When a Live Activity is active, it is shown on both a user's lock screen and Dynamic Island. +When a Live Activity is active, it is shown on both a user's lock screen and Dynamic Island. There are a few different ways for a Live Activity to end and be removed from a user's UI. -There are a few different ways for a Live Activity to end and be removed from a user's UI. * **Time out**: After a default time of 8 hours, iOS will remove the Live Activity from the user's Dynamic Island. After a default time of 12 hours, iOS will remove the Live Activity from the user's lock screen. * **Dismissal date**: You can provide a datetime for a Live Activity to be removed from a user's UI prior to time out. This is defined either in the Activity's `ActivityUIDismissalPolicy` or using the `dismissal_date` parameter in requests to the `/messages/live_activity/update` endpoint. * **End activity**: You can set `end_activity` to `true` in a request to the `/messages/live_activity/update` endpoint to immediately end a Live Activity. @@ -185,5 +184,5 @@ See the [`/messages/live_activity/update`][1] endpoint documentation for full de [2]: https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities#Understand-constraints [3]: https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities [4]: https://developer.apple.com/documentation/activitykit/activityattributes -[5]: braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/ -[6]: braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/resumeactivities(oftype:) \ No newline at end of file +[5]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class +[6]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/resumeactivities(oftype:) \ No newline at end of file From a86da723ed4d6bb9f572fbda69650ea5f02073d2 Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Mon, 27 Feb 2023 17:28:47 -0500 Subject: [PATCH 09/26] Hiding the endpoint from the sidebar --- _docs/_api/endpoints/messaging/live_activity.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_docs/_api/endpoints/messaging/live_activity.md b/_docs/_api/endpoints/messaging/live_activity.md index f68507b46b5..bd6ea179437 100644 --- a/_docs/_api/endpoints/messaging/live_activity.md +++ b/_docs/_api/endpoints/messaging/live_activity.md @@ -1,4 +1,5 @@ --- nav_title: Live Activity config_only: true +hidden: true --- From 3e5eb27e345c97af302742cef2bdb8c8cbe2b507 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 10:10:57 -0500 Subject: [PATCH 10/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: Jeriel Ng --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 4cc3d5a2fd5..90ce7dc73ed 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -46,7 +46,7 @@ First, ensure that you have followed [Displaying live data with Live Activities] Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize the [Activity][4] objects. Importantly, you will define: * `ActivityAttributes`: This protocol defines the static (unchanging) and dynamic (changing) content that will appear in your Live Activity. -* `Activity.ContentState`: This type defines the dynamic data that will be updated over the course of the activity. +* `ActivityAttributes.ContentState`: This type defines the dynamic data that will be updated over the course of the activity. * `ActivityContent`: A structure that encapsulates the Live Activity's structure and additional configuration information. You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices. From 7813d24a53a22888470ebeebc8686f174445abaf Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 10:11:04 -0500 Subject: [PATCH 11/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: Jeriel Ng --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 90ce7dc73ed..1eea7f28fdf 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -34,7 +34,7 @@ To manage the lifecycle of a Live Activity, follow these four steps. 1. [Create the Live Activity.](#developing) Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states. -2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the `launchActivity` method with the Live Activity object and unique activity tag. +2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method with the Live Activity object and unique activity tag. 3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. From 795e49856a53e48f1fd9fc84f8444bf3dbe403ee Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 10:18:41 -0500 Subject: [PATCH 12/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: Jeriel Ng --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 1eea7f28fdf..88ce9d4bec8 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -49,7 +49,7 @@ Because the exact nature of your Live Activity will be specific to your business * `ActivityAttributes.ContentState`: This type defines the dynamic data that will be updated over the course of the activity. * `ActivityContent`: A structure that encapsulates the Live Activity's structure and additional configuration information. -You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices. +You will also use SwiftUI to create the UI presentation of the Lock Screen and Dynamic Island on supported devices. Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. From f6898471e638c09ddf74bda2d7ee9e81861c400b Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 10:19:16 -0500 Subject: [PATCH 13/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: Jeriel Ng --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 88ce9d4bec8..5fffb9c7ea0 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -131,7 +131,7 @@ To do this: 2. Import the `ActivityKit` module if it’s available. 3. Call [`resumeActivities(ofType:)`][6] in `application(_:didFinishLaunchingWithOptions:)` for all `ActivityAttributes` types you have registered in your application. -This allows Braze to resume tasks to track push token updates for all active Live Activities. +This allows Braze to resume tasks to track push token updates for all active Live Activities. Note that if a user has explicitly dismissed the Live Activity on their device, it is considered removed, and Braze will no longer track it. #### Example From 42cdbea54e3036aadfcc661a70ec68be371b7f1b Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Tue, 28 Feb 2023 14:50:36 -0500 Subject: [PATCH 14/26] Responding to comments from GitHub reviewers --- _docs/_api/endpoints/messaging/live_activity/update.md | 10 +++++----- .../swift/live_activities.md | 6 ++---- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index be03b04240f..47ea7fce80d 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -16,7 +16,7 @@ description: "This article outlines details about the Update Live Activity endpo /messages/live_activity/update {% endapimethod %} -Use this endpoint to handle updates for Live Activities displayed by your iOS app. +Use this endpoint to update and end Live Activities displayed by your iOS app. Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. See the [Live Activities article]({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. @@ -80,7 +80,7 @@ There are XX status code responses for this endpoint: `201`, XX, and XX. ### Example success response -The status code `201` could return the following response body. +A `201` status code is returned if the request was formatted correctly and we received the request. The status code `201` could return the following response body. ```json { @@ -92,10 +92,10 @@ The status code `201` could return the following response body. The status code `400` could return the following response body. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. - - ```json - +{ + "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' " +} ``` {% endapi %} \ No newline at end of file diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 5fffb9c7ea0..5896f223024 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -20,8 +20,6 @@ As a developer, you can use Braze to manage your Live Activity lifecycles. Make ## Prerequisites - - {% sdk_min_versions swift:5.11.0 %} Additional prerequisites include: @@ -47,7 +45,6 @@ First, ensure that you have followed [Displaying live data with Live Activities] Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize the [Activity][4] objects. Importantly, you will define: * `ActivityAttributes`: This protocol defines the static (unchanging) and dynamic (changing) content that will appear in your Live Activity. * `ActivityAttributes.ContentState`: This type defines the dynamic data that will be updated over the course of the activity. -* `ActivityContent`: A structure that encapsulates the Live Activity's structure and additional configuration information. You will also use SwiftUI to create the UI presentation of the Lock Screen and Dynamic Island on supported devices. @@ -82,7 +79,7 @@ struct BrazeActivityAttributes: ActivityAttributes { Next, you will use Braze methods to track and manage your Live Activities. -Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. In this instance, you will use ActivityKit to get a push token, which the Braze SDK can manage for you. This allows you to update Live Activities through the Braze API. +Updates to a Live Activity can be sent using ActivityKit (Apple’s framework for managing a Live Activity) or remote push notifications. In this instance, you will use ActivityKit to get a push token, which the Braze SDK can manage for you. This allows you to update Live Activities through the Braze API, as Braze will send the push token to the Apple Push Notification service (APNs) on the backend. 1. Create an instance of your Live Activity implementation using Apple’s ActivityKit APIs. 2. Set the `pushType` parameter as `.token`. @@ -174,6 +171,7 @@ See the [`/messages/live_activity/update`][1] endpoint documentation for full de When a Live Activity is active, it is shown on both a user's lock screen and Dynamic Island. There are a few different ways for a Live Activity to end and be removed from a user's UI. +* **User dismissal**: A user can manually dismiss a Live Activity. * **Time out**: After a default time of 8 hours, iOS will remove the Live Activity from the user's Dynamic Island. After a default time of 12 hours, iOS will remove the Live Activity from the user's lock screen. * **Dismissal date**: You can provide a datetime for a Live Activity to be removed from a user's UI prior to time out. This is defined either in the Activity's `ActivityUIDismissalPolicy` or using the `dismissal_date` parameter in requests to the `/messages/live_activity/update` endpoint. * **End activity**: You can set `end_activity` to `true` in a request to the `/messages/live_activity/update` endpoint to immediately end a Live Activity. From ffe6a2f1fc28c8fc19012bc868fbb0f365be0666 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:01:02 -0500 Subject: [PATCH 15/26] Update _docs/_api/endpoints/messaging/live_activity/update.md Co-authored-by: KellieHawks --- _docs/_api/endpoints/messaging/live_activity/update.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 47ea7fce80d..60c0bf3dd3c 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -16,7 +16,7 @@ description: "This article outlines details about the Update Live Activity endpo /messages/live_activity/update {% endapimethod %} -Use this endpoint to update and end Live Activities displayed by your iOS app. +Use this endpoint to update and end [Live Activities](({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/)) displayed by your iOS app. Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. See the [Live Activities article]({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. From 56bb3aa40270e7432f2202080283dafc4880142d Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:49:39 -0500 Subject: [PATCH 16/26] Apply suggestions from code review Co-authored-by: KellieHawks --- _docs/_api/endpoints/messaging/live_activity/update.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 60c0bf3dd3c..858864f1e12 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -18,7 +18,7 @@ description: "This article outlines details about the Update Live Activity endpo Use this endpoint to update and end [Live Activities](({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/)) displayed by your iOS app. -Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. See the [Live Activities article]({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. +Before using this endpoint, you must register an activity with the Braze Swift SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method. Required request parameters will be defined during this step. Refer to [Live Activities]({{site.baseurl}}/developer_guide/platform_integration_guides/swift/live_activities/) for more information on registration. ## Rate limit @@ -33,15 +33,15 @@ Before using this endpoint, you must register an activity with the Braze Swift S | Parameter | Required | Data Type | Description | |---|---|---|---| | `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-identifier) retrieved from the **Developer Console**. | -| `activity_id` | Required | String | When you register your Live Activity using [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class), 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. | +| `activity_id` | Required | String | When you register your Live Activity using [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class), 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
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter defines 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
([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | This parameter tells the system when the Live Activity content is marked as outdated in the user's UI. | | `notification` | Optional | Object | Include an [`apple_push`]({{site.baseurl}}/api/objects_filters/messaging/apple_object/) object to define a push notification that will also be displayed with this update. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4} -## Example Request +## Example request From 084a1975723bcbe75159e6bb1d822970fd4c1a50 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:50:50 -0500 Subject: [PATCH 17/26] Apply suggestions from code review Co-authored-by: KellieHawks --- .../platform_integration_guides/swift/live_activities.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 5896f223024..854d5ef624f 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -14,9 +14,9 @@ description: "This article covers using Braze to manage your Live Activities tok Live Activities are currently in early access. Contact your Braze account manager if you're interested in participating. {% endalert %} -Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real time. Because they appear on the lock screen, Live Activities ensure that your notifications won't be missed. Because they're persistent, you can display up-to-date content to your users without even having them unlock their phone. +Live Activities are persistent, interactive notifications displayed on your lock screen, allowing you to keep an eye on things in real-time. Because they appear on the lock screen, Live Activities ensure that your notifications won't be missed. Because they're persistent, you can display up-to-date content to your users without even having them unlock their phone. -As a developer, you can use Braze to manage your Live Activity lifecycles. Make calls to the Braze REST API to make Live Activity updates and have all subscribed devices receive the update as quickly as possible. And, because you're managing Live Activities through Braze, you can use them in tandem with your other messaging channels—push notifications, in-app messages, Content Cards—to drive adoption. +As a developer, you can use Braze to manage your Live Activity lifecycles, make calls to the Braze REST API to make Live Activity updates, and have all subscribed devices receive the update as quickly as possible. And, because you're managing Live Activities through Braze, you can use them in tandem with your other messaging channels—push notifications, in-app messages, Content Cards—to drive adoption. ## Prerequisites @@ -24,7 +24,7 @@ As a developer, you can use Braze to manage your Live Activity lifecycles. Make Additional prerequisites include: * Live Activities are only available for iPhones on iOS 16.1 and later. To use this feature, ensure that your project is targeting this iOS version. -* The `Push Notification` entitlement must be added under Signing & Capabilities in your Xcode project. +* The `Push Notification` entitlement must be added under **Signing & Capabilities** in your Xcode project. ## Implementing a Live Activity From 5feb7ed118d3edc15ccd1dcc057947a983346819 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:51:09 -0500 Subject: [PATCH 18/26] Apply suggestions from code review Co-authored-by: KellieHawks --- .../platform_integration_guides/swift/live_activities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 854d5ef624f..8352108f174 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -30,9 +30,9 @@ Additional prerequisites include: To manage the lifecycle of a Live Activity, follow these four steps. -1. [Create the Live Activity.](#developing) Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states. +1. [Create the Live Activity.](#developing) Develop the Live Activity UI using WidgetKit and SwiftUI. Initialize a Live Activity object with the relevant data models for your static and dynamic states.

-2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method with the Live Activity object and unique activity tag. +2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method with the Live Activity object and unique activity tag.

3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. From 6988627ee19f22c4f9177ab13d77a7259abe3165 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:51:42 -0500 Subject: [PATCH 19/26] Apply suggestions from code review Co-authored-by: KellieHawks --- .../platform_integration_guides/swift/live_activities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 8352108f174..971aeea2810 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -34,13 +34,13 @@ To manage the lifecycle of a Live Activity, follow these four steps. 2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method with the Live Activity object and unique activity tag.

-3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`. +3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`.

4. [End the Live Activity](#ending) End a Live Activity for all recipients by publishing an update to `/messages/live_activity/update` with the parameter `"end_activity": true`. ## Step 1: Developing your Live Activity {#developing} -First, ensure that you have followed [Displaying live data with Live Activities][3] in Apple’s documentation to set up Live Activities in your iOS application. As part of this task, make sure you include `NSSupportsLiveActivities` set to `YES` in your `Info.plist`. +First, ensure that you have followed [Displaying live data with Live Activities][3] in Apple’s documentation to set up Live Activities in your iOS application. As part of this task, make sure you include `NSSupportsLiveActivities` set to `YES` in your `Info.plist`. Because the exact nature of your Live Activity will be specific to your business case, you will need to set up and initialize the [Activity][4] objects. Importantly, you will define: * `ActivityAttributes`: This protocol defines the static (unchanging) and dynamic (changing) content that will appear in your Live Activity. From eeef053cf4d074da5662bc955f125eee1454510d Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:51:55 -0500 Subject: [PATCH 20/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: KellieHawks --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 971aeea2810..a55f7e30fb4 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -36,7 +36,7 @@ To manage the lifecycle of a Live Activity, follow these four steps. 3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`.

-4. [End the Live Activity](#ending) End a Live Activity for all recipients by publishing an update to `/messages/live_activity/update` with the parameter `"end_activity": true`. +4. [End the Live Activity](#ending) End a Live Activity for all recipients by publishing an update to [`/messages/live_activity/update`]({{site.baseurl}}/api/endpoints/messaging/live_activity/update) with the parameter `"end_activity": true`. ## Step 1: Developing your Live Activity {#developing} From f5caf81ee17ef5411036df5936b71f1d763540f5 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:52:11 -0500 Subject: [PATCH 21/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: KellieHawks --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index a55f7e30fb4..0760931fe09 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -51,7 +51,7 @@ You will also use SwiftUI to create the UI presentation of the Lock Screen and D Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. {% alert note %} -If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by Apple's budget limit by adding `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your `Info.plist` file. For more details, refer to the [`Determine the update frequency`](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency) section in the ActivityKit documentation. +If you expect to send frequent pushes to the same Live Activity, you can avoid being throttled by Apple's budget limit by setting `NSSupportsLiveActivitiesFrequentUpdates` to `YES` in your `Info.plist` file. For more details, refer to the [`Determine the update frequency`](https://developer.apple.com/documentation/activitykit/updating-and-ending-your-live-activity-with-activitykit-push-notifications#Determine-the-update-frequency) section in the ActivityKit documentation. {% endalert %} ### Example From ccc6b92fa2e22eddbc936b8412e2026ca939bf5d Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 15:54:39 -0500 Subject: [PATCH 22/26] Apply suggestions from code review --- .../platform_integration_guides/swift/live_activities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 0760931fe09..39d0f90f80e 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -34,7 +34,7 @@ To manage the lifecycle of a Live Activity, follow these four steps. 2. [Register the Live Activity](#registering) Register a Live Activity with the Braze SDK using the [`launchActivity`](https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/launchactivity(pushtokentag:activity:fileid:line:)) method with the Live Activity object and unique activity tag.

-3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze API endpoint `/messages/live_activity/update`.

+3. [Update the Live Activity](#updating) Publish updates to the Live Activity using the Braze [`/messages/live_activity/update`]({{site.baseurl}}/api/endpoints/messaging/live_activity/update) API endpoint.

4. [End the Live Activity](#ending) End a Live Activity for all recipients by publishing an update to [`/messages/live_activity/update`]({{site.baseurl}}/api/endpoints/messaging/live_activity/update) with the parameter `"end_activity": true`. @@ -183,4 +183,4 @@ See the [`/messages/live_activity/update`][1] endpoint documentation for full de [3]: https://developer.apple.com/documentation/activitykit/displaying-live-data-with-live-activities [4]: https://developer.apple.com/documentation/activitykit/activityattributes [5]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class -[6]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/resumeactivities(oftype:) \ No newline at end of file +[6]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/liveactivities-swift.class/resumeactivities(oftype:) From f722cb765d64b329e2b196c2092b8922a2d3e10e Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 16:02:11 -0500 Subject: [PATCH 23/26] Update _docs/_api/endpoints/messaging/live_activity/update.md Co-authored-by: KellieHawks --- _docs/_api/endpoints/messaging/live_activity/update.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 858864f1e12..6b581701484 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -26,6 +26,8 @@ Before using this endpoint, you must register an activity with the Braze Swift S {% multi_lang_include rate_limits.md endpoint='default' category='message endpoints' %} +## Request body + ## Request parameters From 951c882de58ac3a8aae370c0bd1ece7e2eefdee6 Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Tue, 28 Feb 2023 16:05:06 -0500 Subject: [PATCH 24/26] Added request body --- .../_api/endpoints/messaging/live_activity/update.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index 6b581701484..fddd1f194d3 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -28,6 +28,18 @@ Before using this endpoint, you must register an activity with the Braze Swift S ## Request body +```json +{ + "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) when 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 will also be displayed with this update." + } + ``` + ## Request parameters From a806b2d717cc4de18d73fed505300a868f218752 Mon Sep 17 00:00:00 2001 From: Josh McCrowell <113209750+josh-mccrowell-braze@users.noreply.github.com> Date: Tue, 28 Feb 2023 17:00:22 -0500 Subject: [PATCH 25/26] Update _docs/_developer_guide/platform_integration_guides/swift/live_activities.md Co-authored-by: KellieHawks --- .../platform_integration_guides/swift/live_activities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md index 39d0f90f80e..f0d3ffda1bf 100644 --- a/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md +++ b/_docs/_developer_guide/platform_integration_guides/swift/live_activities.md @@ -46,7 +46,7 @@ Because the exact nature of your Live Activity will be specific to your business * `ActivityAttributes`: This protocol defines the static (unchanging) and dynamic (changing) content that will appear in your Live Activity. * `ActivityAttributes.ContentState`: This type defines the dynamic data that will be updated over the course of the activity. -You will also use SwiftUI to create the UI presentation of the Lock Screen and Dynamic Island on supported devices. +You will also use SwiftUI to create the UI presentation of the lock screen and Dynamic Island on supported devices. Make sure you're familiar with Apple's [prerequisites and limitations][2] for Live Activities, as these constraints are independent from Braze. From 66a7612c81545d1f4c9ba9119da8220a473c9e1d Mon Sep 17 00:00:00 2001 From: "joshua.mccrowell" Date: Tue, 28 Feb 2023 17:06:36 -0500 Subject: [PATCH 26/26] Updated notification and removed answered questions --- .../messaging/live_activity/update.md | 24 ++++++------------- 1 file changed, 7 insertions(+), 17 deletions(-) diff --git a/_docs/_api/endpoints/messaging/live_activity/update.md b/_docs/_api/endpoints/messaging/live_activity/update.md index fddd1f194d3..040b0967f07 100644 --- a/_docs/_api/endpoints/messaging/live_activity/update.md +++ b/_docs/_api/endpoints/messaging/live_activity/update.md @@ -22,8 +22,6 @@ Before using this endpoint, you must register an activity with the Braze Swift S ## Rate limit - - {% multi_lang_include rate_limits.md endpoint='default' category='message endpoints' %} ## Request body @@ -42,8 +40,6 @@ Before using this endpoint, you must register an activity with the Braze Swift S ## Request parameters - - | Parameter | Required | Data Type | Description | |---|---|---|---| | `app_id` | Required | String | App [API identifier]({{site.baseurl}}/api/identifier_types/#the-app-identifier) retrieved from the **Developer Console**. | @@ -57,8 +53,6 @@ Before using this endpoint, you must register an activity with the Braze Swift S ## Example request - - ```json curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_activity/update \ --header 'Content-Type: application/json' \ @@ -74,9 +68,9 @@ curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_acti "dismissal_date": "2023-02-28T00:00:00+0000", "stale_date": "2023-02-27T16:55:49+0000", "notification": { - "apple_push": { - "alert": "Halftime!", - "badge": 1 + "alert": { + "body": "It's halftime! Let's look at the scores", + "title": "Halftime" } } } @@ -84,13 +78,7 @@ curl --location --request POST 'https://rest.iad-01.braze.com/messages/live_acti ## Response - - -There are XX status code responses for this endpoint: `201`, XX, and XX. - -### Response parameters - - +There are two status code responses for this endpoint: `201` and `4XX`. ### Example success response @@ -104,7 +92,9 @@ A `201` status code is returned if the request was formatted correctly and we re ### Example error response -The status code `400` could return the following response body. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. +The `4XX` class of status code indicates a client error. Refer to the [API errors and responses article]({{site.baseurl}}/api/errors/) for more information about errors you may encounter. + +The status code `400` could return the following response body. ```json {