From 2e5bf5d788458c9baf8b64a041e0266bd54bfe8f Mon Sep 17 00:00:00 2001 From: Eliab <123114801+eliabsisay@users.noreply.github.com> Date: Tue, 4 Mar 2025 09:48:12 -0800 Subject: [PATCH 1/3] Create Data-Marshaling-and-Transmission.md --- .../Data-Marshaling-and-Transmission.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/product/Data-Marshaling-and-Transmission.md diff --git a/docs/product/Data-Marshaling-and-Transmission.md b/docs/product/Data-Marshaling-and-Transmission.md new file mode 100644 index 00000000..9d64bfd5 --- /dev/null +++ b/docs/product/Data-Marshaling-and-Transmission.md @@ -0,0 +1,38 @@ +--- +title: Data Marshaling and Transmission +sidebar_position: 11 +description: How Embrace sends data off device +--- + +# Overview + +--- + +Embrace is designed to be a “good citizen” within your mobile application. We’re aware that many of our customers have critical user journeys (such as completing a transaction) that cannot be interrupted or slowed by non-essential network activity. To address these concerns: + +- **Data is batched and sent on a low-priority basis.** +- **We avoid sending if we detect there is no network** and use an exponential backoff when connectivity is poor. +- **We never send more than one request at a time**, minimizing the chance of saturating the network. +- **We do not share any domain or session resources** with your primary application requests, so there is no direct contention with your core APIs. + +These design principles ensure that user-facing requests (such as booking flows, checkouts, or other high-priority transactions) always receive the highest priority on the device and network. + +# FAQ’s + +--- + +## **Will Embrace SDK’s network requests block or slow down my main APIs?** + +No. We send data in small, batched increments and only one batch at a time. On Android, this is a single network call at a time. On iOS, we use a separate URLSession with lower priority. This ensures Embrace’s requests do not interfere with higher-priority user or application traffic. + +## **What happens if the user is on a weak connection?** + +We employ exponential backoff for retries when a connection fails and do not attempt to send if the device is offline. This prevents us from continuously saturating a weak or nonexistent network. + +## **Can we configure the SDK to only send data when on Wi-Fi or in the background?** + +Currently, no. We prioritize quick, low-frequency uploads to avoid large backlogs and ensure timely observability. Restricting uploads to Wi-Fi or background-only would risk missing critical data if the app is not backgrounded for a long enough period or closed altogether. + +## **Is it possible to disable data sending entirely during critical user flows?** + +We do not offer an official toggle for this. However, if needed, please reach out to discuss advanced use cases. Be aware that disabling data transmission for extended periods can create gaps in observability. From b1eab0d00f538a8eee4db2c722a34ca2bfe5a70c Mon Sep 17 00:00:00 2001 From: Hanson Ho Date: Tue, 4 Mar 2025 10:09:54 -0800 Subject: [PATCH 2/3] Clarify details between Android and iOS --- docs/product/Data-Marshaling-and-Transmission.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/product/Data-Marshaling-and-Transmission.md b/docs/product/Data-Marshaling-and-Transmission.md index 9d64bfd5..f8295395 100644 --- a/docs/product/Data-Marshaling-and-Transmission.md +++ b/docs/product/Data-Marshaling-and-Transmission.md @@ -10,12 +10,13 @@ description: How Embrace sends data off device Embrace is designed to be a “good citizen” within your mobile application. We’re aware that many of our customers have critical user journeys (such as completing a transaction) that cannot be interrupted or slowed by non-essential network activity. To address these concerns: -- **Data is batched and sent on a low-priority basis.** -- **We avoid sending if we detect there is no network** and use an exponential backoff when connectivity is poor. -- **We never send more than one request at a time**, minimizing the chance of saturating the network. +- **Data is batched and tranmitted to balance reliability with resource usage.** + - On Android, requests are sent serially, i.e. only one payload is actively being sent at one time. + - On iOS, payloads are enqueued with a low-priority. +- **We do not send data if we detect there is no network connection** and use an exponential backoff scheme to handle retries so the queue wouldn't be overwhelmed by requests timing out if the network condition is poor. - **We do not share any domain or session resources** with your primary application requests, so there is no direct contention with your core APIs. -These design principles ensure that user-facing requests (such as booking flows, checkouts, or other high-priority transactions) always receive the highest priority on the device and network. +These design principles ensure that user-facing requests (such as booking flows, checkouts, or other high-priority transactions) will be impacted as little as possible by the overhead of transimitting telemetry. # FAQ’s @@ -23,11 +24,11 @@ These design principles ensure that user-facing requests (such as booking flows, ## **Will Embrace SDK’s network requests block or slow down my main APIs?** -No. We send data in small, batched increments and only one batch at a time. On Android, this is a single network call at a time. On iOS, we use a separate URLSession with lower priority. This ensures Embrace’s requests do not interfere with higher-priority user or application traffic. +No. We send data in small, batched increments and only one batch at a time. On Android, this is a single network call at a time. On iOS, we use a separate URLSession with lower priority. This ensures Embrace’s requests do not interfere with higher-priority user or application traffic and limits bandwidth consumption. ## **What happens if the user is on a weak connection?** -We employ exponential backoff for retries when a connection fails and do not attempt to send if the device is offline. This prevents us from continuously saturating a weak or nonexistent network. +We employ exponential backoff for retries when a connection fails and do not attempt to send if the device is offline. This means that if the first request fails, we retry in 1 minute, then 2 minutes, then 4 minutes, doubling at every interval. This prevents us from continuously saturating a weak network when timeouts or transmission failure are likely. ## **Can we configure the SDK to only send data when on Wi-Fi or in the background?** From a609c1d2acaca083b087b23a231a1ae0f78bc4d5 Mon Sep 17 00:00:00 2001 From: Eliab <123114801+eliabsisay@users.noreply.github.com> Date: Tue, 4 Mar 2025 11:22:13 -0800 Subject: [PATCH 3/3] Update Data-Marshaling-and-Transmission.md --- docs/product/Data-Marshaling-and-Transmission.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/product/Data-Marshaling-and-Transmission.md b/docs/product/Data-Marshaling-and-Transmission.md index f8295395..02ce05a2 100644 --- a/docs/product/Data-Marshaling-and-Transmission.md +++ b/docs/product/Data-Marshaling-and-Transmission.md @@ -1,7 +1,7 @@ --- title: Data Marshaling and Transmission sidebar_position: 11 -description: How Embrace sends data off device +description: How about keeping it simple with something like "How Embrace SDKs Transfer Data from Devices to Our Servers --- # Overview @@ -13,12 +13,12 @@ Embrace is designed to be a “good citizen” within your mobile application. W - **Data is batched and tranmitted to balance reliability with resource usage.** - On Android, requests are sent serially, i.e. only one payload is actively being sent at one time. - On iOS, payloads are enqueued with a low-priority. -- **We do not send data if we detect there is no network connection** and use an exponential backoff scheme to handle retries so the queue wouldn't be overwhelmed by requests timing out if the network condition is poor. +- **We do not send data if we detect there is no network connection** and use an exponential backoff scheme to handle retries so the queue won't be overwhelmed by requests timing out if the network condition is poor. - **We do not share any domain or session resources** with your primary application requests, so there is no direct contention with your core APIs. These design principles ensure that user-facing requests (such as booking flows, checkouts, or other high-priority transactions) will be impacted as little as possible by the overhead of transimitting telemetry. -# FAQ’s +# FAQs --- @@ -32,7 +32,7 @@ We employ exponential backoff for retries when a connection fails and do not att ## **Can we configure the SDK to only send data when on Wi-Fi or in the background?** -Currently, no. We prioritize quick, low-frequency uploads to avoid large backlogs and ensure timely observability. Restricting uploads to Wi-Fi or background-only would risk missing critical data if the app is not backgrounded for a long enough period or closed altogether. +No. We prioritize quick, low-frequency uploads to avoid large backlogs and ensure timely observability. Restricting uploads to Wi-Fi or background-only would risk missing critical data if the app is not backgrounded for a long enough period or closed altogether. ## **Is it possible to disable data sending entirely during critical user flows?**