[BD-5174] Clarify logging_message_data.md is only for custom push notification handlers

_docs/_developer_guide/push_notifications/logging_message_data.md

@@ -2,13 +2,19 @@
 nav_title: Logging message data
 article_title: Logging push notification data through the Braze SDK
 page_order: 7.2
-description: "Learn how to log push notification data through the Braze SDK."
+description: "Learn how to log push notification data through the Braze SDK when using custom notification handling."
 noindex: true
 ---
 
 # Logging push notification data
 
-> Learn how to log push notification data through the Braze SDK.
+> Learn how to log push notification data when implementing custom push notification handling.
+
+{% alert important %}
+This page is only relevant if you're implementing custom push notification handling and bypassing the Braze SDK's default push notification processing. Most users do not need this information—the Braze SDK automatically handles push notification analytics when you follow the standard integration guide.
+{% endalert %}
+
+If you're using the Braze SDK's default push notification handling, analytics (opens, receives, dismisses) are logged automatically. You only need the instructions on this page if you've implemented custom notification handling logic that bypasses Braze's automatic processing.
 
 {% sdktabs %}
 {% sdktab android %}

_includes/developer_guide/android/analytics/logging_push_data.md

@@ -1,9 +1,35 @@
 ## Logging data with the Braze API (recommended)
 
-You can log analytics in real-time by making calls to the [`/users/track` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_user_track/). To log analytics, send the `braze_id` value from the Braze dashboard to identify which user profile to update.
+If you're handling push notifications with custom code instead of using the Braze SDK's default notification handling, you can log analytics in real-time by making calls to the [`/users/track` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_user_track/). 
+
+### Step 1: Pass the Braze ID in your push payload
+
+To identify which user profile to update, include the `braze_id` value as a key-value pair in your push notification payload when creating the campaign in the Braze dashboard.
 
 ![Personalized Push dashboard Example]({% image_buster /assets/img/push_implementation_guide/android_braze_id_configuration.png %}){: style="max-width:79%;"}
 
+### Step 2: Extract the Braze ID and call the API
+
+In your custom notification handler, extract the `braze_id` from the notification payload and make a server-side call to the [`/users/track` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_user_track/) to log the appropriate event (such as push opened, push received, or a custom event). You'll need to send this request from your server using your Braze REST API key.
+
+The `/users/track` endpoint can identify users using either `braze_id` or `external_id`. For example, to log a push open event using the `braze_id`:
+
+```json
+{
+  "events": [
+    {
+      "braze_id": "abc123xyz",
+      "name": "push_notification_opened",
+      "time": "2024-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+Alternatively, if you have the user's `external_id`, you can use that instead of `braze_id` in your API call.
+
 ## Manually logging data
 
-Depending on the details of your payload, you can log analytics manually within your `FirebaseMessagingService.onMessageReceived` implementation or your startup activity. Keep in mind, your `FirebaseMessagingService` subclass must finish execution within 9 seconds of invocation to avoid being [flagged or terminated](https://firebase.google.com/docs/cloud-messaging/android/receive) by the Android system.
+Alternatively, depending on the details of your payload, you can log analytics manually within your `FirebaseMessagingService.onMessageReceived` implementation or your startup activity by calling the appropriate Braze SDK methods directly (such as `Braze.logPushNotificationOpened()`). 
+
+Keep in mind that your `FirebaseMessagingService` subclass must finish execution within 9 seconds of invocation to avoid being [flagged or terminated](https://firebase.google.com/docs/cloud-messaging/android/receive) by the Android system.

_includes/developer_guide/swift/analytics/logging_push_data.md

@@ -1,14 +1,40 @@
 ## Logging data with the Braze API (recommended)
 
-Logging analytics can be done in real-time with the help of the Braze API [`/users/track` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_user_track/). To log analytics, send down the `braze_id` value in the key-value pairs field (as seen in the following screenshot) to identify which user profile to update.
+If you're handling push notifications with custom code instead of using the Braze SDK's default notification handling, you can log analytics in real-time with the help of the Braze API [`/users/track` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_user_track/).
+
+### Step 1: Pass the Braze ID in your push payload
+
+To identify which user profile to update, include the `braze_id` value as a key-value pair in your push notification payload when creating the campaign in the Braze dashboard (as seen in the following screenshot).
 
 ![A push message with three sets of key-value pairs. 1. "Braze_id" set as a Liquid call to retrieve Braze ID. 2. "cert_title" set as "Braze Marketer Certification". 3. "Cert_description" set as "Certified Braze marketers drive...".]({% image_buster /assets/img/push_implementation_guide/push18.png %}){: style="max-width:80%;"}
 
+### Step 2: Extract the Braze ID and call the API
+
+In your custom notification handler, extract the `braze_id` from the notification payload and make a server-side call to the [`/users/track` endpoint]({{site.baseurl}}/api/endpoints/user_data/post_user_track/) to log the appropriate event (such as push opened, push received, or a custom event). You'll need to send this request from your server using your Braze REST API key.
+
+The `/users/track` endpoint can identify users using either `braze_id` or `external_id`. For example, to log a push open event using the `braze_id`:
+
+```json
+{
+  "events": [
+    {
+      "braze_id": "abc123xyz",
+      "name": "push_notification_opened",
+      "time": "2024-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+Alternatively, if you have the user's `external_id`, you can use that instead of `braze_id` in your API call.
+
 ## Logging data manually
 
-Logging manually will require you to first configure workspaces within Xcode, and then create, save, and retrieve analytics. This will require some custom developer work on your end. The following code snippets shown will help address this. 
+Logging manually will require you to first configure workspaces within Xcode, and then create, save, and retrieve analytics. This approach requires custom developer work on your end. The following code snippets will help address this. 
+
+### Important timing considerations
 
-It's important to note that analytics are not sent to Braze until the mobile application is subsequently launched. This means that, depending on your dismissal settings, there often exists an indeterminate period of time between when a push notification is dismissed and the mobile app is launched and the analytics are retrieved. While this time buffer may not affect all use cases, you should consider this impact adjust your user journey as necessary to include opening the application to address this concern. 
+It's important to note that analytics are not sent to Braze until the mobile application is subsequently launched. This means that, depending on your dismissal settings, there often exists an indeterminate period of time between when a push notification is dismissed and the mobile app is launched and the analytics are retrieved. While this time buffer may not affect all use cases, you should consider this impact and adjust your user journey as necessary to include opening the application to address this concern. 
 
 ![A graphic describing how analytics are processed in Braze. 1. Analytics data is created. 2. Analytics data is saved. 3. Push notification is dismissed. 4. Indeterminate period of time between when push notification is dismissed and mobile app is launched. 5. Mobile app is launched. 6. Analytics data is received. 7. Analytics data is sent to Braze.]({% image_buster /assets/img/push_implementation_guide/push13.png %})