diff --git a/src/connections/destinations/catalog/actions-batch/images/attributes_mapping.png b/src/connections/destinations/catalog/actions-batch/images/attributes_mapping.png new file mode 100644 index 0000000000..5eea55b773 Binary files /dev/null and b/src/connections/destinations/catalog/actions-batch/images/attributes_mapping.png differ diff --git a/src/connections/destinations/catalog/actions-batch/images/basic_settings_destination.png b/src/connections/destinations/catalog/actions-batch/images/basic_settings_destination.png new file mode 100644 index 0000000000..a020e5abe9 Binary files /dev/null and b/src/connections/destinations/catalog/actions-batch/images/basic_settings_destination.png differ diff --git a/src/connections/destinations/catalog/actions-batch/images/events_mapping.png b/src/connections/destinations/catalog/actions-batch/images/events_mapping.png new file mode 100644 index 0000000000..60a16f9f74 Binary files /dev/null and b/src/connections/destinations/catalog/actions-batch/images/events_mapping.png differ diff --git a/src/connections/destinations/catalog/actions-batch/images/test_record.png b/src/connections/destinations/catalog/actions-batch/images/test_record.png new file mode 100644 index 0000000000..aea3daf33c Binary files /dev/null and b/src/connections/destinations/catalog/actions-batch/images/test_record.png differ diff --git a/src/connections/destinations/catalog/actions-batch/index.md b/src/connections/destinations/catalog/actions-batch/index.md new file mode 100644 index 0000000000..e556073b22 --- /dev/null +++ b/src/connections/destinations/catalog/actions-batch/index.md @@ -0,0 +1,206 @@ +--- +title: Batch (Actions) Destination +id: 596d11f870a3e552b957e6d9 +--- + +{% include content/plan-grid.md name="actions" %} + +[Batch](https://batch.com/?utm_source=segmentio&utm_medium=docs&utm_campaign=partners){:target="_blank"} is a customer engagement platform for personalized, timely notifications and messages that boost retention and drive growth. + +This destination is maintained by Batch. For any issues, [contact Batch Support](mailto:support@batch.com){:target="_blank"}. + +## Getting started + +1. From your workspace’s [destinations catalog](https://app.segment.com/goto-my-workspace/destinations/catalog){:target="_blank"}, search for **Batch**. +2. Select **Batch (Actions)** and click **Add Destination**. +3. Choose the **source** you want to connect to **Batch (Actions)**. +4. In the [Batch dashboard](https://dashboard.batch.com/){:target="_blank"}, copy your **Project Key** and **REST API Key**. +5. Paste the **Project Key** and **REST API Key** into the Batch destination settings in Segment. +6. Toggle **Enable Destination**. Segment will start sending data to Batch according to your **Mappings**. + +![Basic settings destination](./images/basic_settings_destination.png "Basic settings destination") + +{% include components/actions-fields.html %} + +## Profile attributes mapping + +> info "" +> If you’re new to the Identify call, see the [Segment spec](/docs/connections/spec/identify/) for more details. + +When you call **Identify**, Segment maps `userId` to **`identifiers.custom_id`** and writes traits into **`attributes`**. + +### Example Identify call (Segment input) + +```js +analytics.identify("97980cfea0067", { + name: "Peter Gibbons", + email: "peter@example.com", + phone: "+33600000000", + email_marketing: "subscribed", + sms_marketing: "unsubscribed", + plan: "premium", + logins: 5 +}, { + context: { + timezone: "Europe/Paris", + locale: "fr-FR" + } +}); +``` + +### Auto-mapped fields (native) + +| Segment field | Batch field | +|----------------------------------------|---------------------------------| +| `userId` | `identifiers.custom_id` | +| `traits.email` | `attributes.$email_address` | +| `traits.phone` | `attributes.$phone_number` | +| `traits.email_marketing` | `attributes.$email_marketing` | +| `traits.sms_marketing` | `attributes.$sms_marketing` | +| `context.timezone` | `attributes.$timezone` | +| `context.locale` → language *(for example: `fr`)*| `attributes.$language` | +| `context.locale` → region *(for example: `FR`)* | `attributes.$region` | + +**Notes** + +- `$email_marketing` / `$sms_marketing`: use `subscribed` / `unsubscribed`. +- A locale like `fr-FR` is split into **language** (`fr`) and **region** (`FR`). +- All other non‑reserved fields become **custom attributes** under `attributes` (strings, numbers, booleans, arrays of strings). Avoid arbitrary nested objects. + +> info "" +> For more details on the fields to be included, refer to the Batch [API Profile documentation](https://doc.batch.com/developer/api/cep/profiles/update){:target="_blank"}. + +### Resulting Batch profile payload (output) + +```json +{ + "identifiers": { + "custom_id": "97980cfea0067" + }, + "attributes": { + "$email_address": "peter@example.com", + "$phone_number": "+33600000000", + "$email_marketing": "subscribed", + "$sms_marketing": "unsubscribed", + "$language": "fr", + "$region": "FR", + "$timezone": "Europe/Paris", + + "name": "Peter Gibbons", + "plan": "premium", + "logins": 5 + } +} +``` + +### Add custom mappings + +To map additional traits into Batch profile attributes: + +1. Open your destination → **Mappings** → **Edit Mapping**. +2. Go to **Profile attributes** → **Add Mapping Field**. +3. Choose a **source** (for example, `traits.plan`) and set a **target** under `attributes` (for example, `attributes.plan`). +![Attributes mapping](./images/attributes_mapping.png "Attributes mapping") +4. In **Step 4 – Send test record**, you can test your mapping before saving. +![Test record](./images/test_record.png "Test record") +5. **Save** and enable the mapping. + +> info "Supported types" +> Strings, numbers, booleans, arrays of strings are supported. +> Avoid arbitrary nested objects. + +## Historical backfill request + +If you want to integrate your entire Segment userbase into Batch using the **Identify** method, you can request a historical backfill from Segment. + +To do this: + +1. **Contact Segment Support** at [friends@segment.com](mailto:friends@segment.com). +2. **Request a historical replay** of your data. +3. Provide Segment with the following details: + - **Start date and time** + - **End date and time** (usually “now”) + - **Source**: the Segment source you want to replay + - **Destination**: **Batch (Actions)** + - **Events**: `Identify` + +Segment will then replay your historical data so Batch can import your full userbase. + +## Profile events mapping + +When you call **Track**, Segment uses your `userId` as Batch’s **`identifiers.custom_id`**. A **userId is required** to attribute the event to a profile. + +> info "" +> For more details on the Track call, see the [Track spec](/docs/connections/spec/track). + +### Example Track call (Segment input) + +```js +analytics.track("User Registered", { + plan: "Pro Annual", + accountType: "Facebook" +}, { + userId: "97980cfea0067" +}); +``` + +### How Segment maps to Batch + +| Segment | Batch | +|-------------------|-------------------------| +| `userId` | `identifiers.custom_id` | +| `event` | `event.name` | +| `properties.*` | `event.attributes.*` | + +### Resulting Batch event payload (output) + +```json +{ + "identifiers": { + "custom_id": "97980cfea0067" + }, + "event": { + "name": "User Registered", + "attributes": { + "plan": "Pro Annual", + "accountType": "Facebook" + } + } +} +``` + +Events are sent to Batch in near real time according to your destination mappings, and all event `properties` are included under `event.attributes`. + +![Events mapping](./images/events_mapping.png "Events mapping") + +## Validation checklist + +- Always send a stable `userId` → becomes `identifiers.custom_id`. +- Place native profile fields under `attributes`: `$email_address`, `$email_marketing`, `$phone_number`, `$sms_marketing`, `$language`, `$region`, `$timezone`. +- Put everything else under **custom attributes** in `attributes`. +- Format dates using **ISO‑8601 UTC** (for example: `1989-07-20T00:00:00Z`). +- Configure additional mappings in **Mappings → Edit Mapping**. +- Test with a read-back or export to verify types, encodings, and timezones. + +## Integrating a computed trait + +> info "" +> For more details on computed traits, see the [Segment spec](/docs/unify/Traits/computed-traits). + +To integrate a computed trait with Batch: + +1. Go to your **Segment workspace**. +2. Open the **Engage** tab → **Destinations**. + - If your Batch destination is already listed, skip this step. + - Otherwise, click **Add destination** and select **Batch (Actions)**. +3. Open the **Engage** tab → **Audiences** → **Computed traits**. +4. Click **Create computed trait**. +5. Configure your **calculation method** (for example: count, aggregation, last value). +6. Click **Preview**, then **Next**. +7. Select your **Batch destination**. +8. Choose how to send the data: + - For an attribute → enable **Send Identify** in the connection settings. + - For an event → enable **Send Track**. +9. Give your computed trait a **clear name**. + +Segment will then automatically update and forward your computed trait data to Batch. diff --git a/src/connections/destinations/catalog/batch/index.md b/src/connections/destinations/catalog/batch/index.md index 560aaef561..200280a450 100644 --- a/src/connections/destinations/catalog/batch/index.md +++ b/src/connections/destinations/catalog/batch/index.md @@ -1,101 +1,21 @@ --- title: Batch Destination -id: 596d11f870a3e552b957e6d9 --- -The Batch.com integration code is open sourced on GitHub. Feel free to check it out: [iOS](https://github.com/BatchLabs/ios-segment-integration){:target="_blank"}, [Android](https://github.com/BatchLabs/android-segment-integration){:target="_blank"}. -## Getting Started +{% include content/plan-grid.md name="actions" %} -* Batch.com supports the `screen`, `track`, `identify` and `group` methods. -* Make a Batch.com account. -* Turn on Batch.com using Segment dashboard. -* Enter your Batch LIVE API Key. You can find it in your dashboard, under 'settings'. +Batch is a powerful customer engagement platform that helps businesses deliver personalized, timely notifications and messages to boost user retention and drive growth. Discover how Batch can transform your communication strategy at Batch. -Events tracked using Segment's `track`/`screen` will automatically be tracked. `Identify` and `group` calls will also be mapped to Batch user data. +This destination is maintained by Batch. For any issues with the destination, [contact their Support team](mailto:support@batch.com). -## Android +## Getting started -### Installation +1. From your workspace's [Destination catalog page](https://app.segment.com/goto-my-workspace/destinations/catalog){:target="_blank"} search for Batch. +2. Select **Batch** and click **Add Destination**. +3. Select an existing Source to connect to Batch (Actions). +4. Go to the [Batch dashboard](https://dashboard.batch.com/){:target="_blank"}, find and copy the **Project Key** / **REST API Key** +5. Enter the **Project Key** / **REST API Key** in the Batch destination settings in Segment. -Add the following dependency in your build.gradle: -``` -compile "com.batch.android:sdk-segment-integration:+" -``` - -Import the integration: - -``` -import com.segment.analytics.android.integrations.batch.BatchIntegration; - -``` - -Then, add the factory to your Analytics instance: - -```java -Analytics analytics = new Analytics.Builder(this, "write_key") - .use(BatchIntegration.getFactory(this)) - .build(); -``` - - -## iOS - -### Installation - -Add the following Cocoapods dependency: - -``` -pod 'Segment-Batch' -``` - -If you integrate in a Swift project or have `use_frameworks!` in your Podfile, you need to use the following to work around due to a limitation with Cocoapods: - -``` -pod 'Batch' -pod 'Segment-Batch/StaticLibWorkaround' -``` - -Then, add the integration factory in your Analytics instance: - -```objc -#import - -SEGAnalyticsConfiguration *config = [SEGAnalyticsConfiguration configurationWithWriteKey:@"MySegmentWriteKey"]; -[config use:[SEGBatchIntegrationFactory instance]]; -[SEGAnalytics setupWithConfiguration:config]; -``` - -## Server Side - -You can transmit server-side data from Segment to Batch with a [destination function](/docs/connections/functions/destination-functions/). Follow the steps outlined [in Batch's documentation](https://help.batch.com/en/articles/2208243-how-to-connect-batch-to-segment){:target="_blank"} for a smooth integration. - -## Screen - -When you call `screen` in your mobile app, we send a screen view to an event named `SEGMENT_SCREEN`. The screen name will be tracked as the event's label. - -## Identify - -When you `identify` a user, we'll pass that user's information to Batch as the custom user identifier. Batch supports tracking anonymous users, but not through Segment's `anonymousId`. - -Tracked events are attached to the installation ID, and the installation ID itself can be attached/detached to a user at a later date, with no data loss. - -## Track - -When you `track` an event, we will send that event to Batch after converting the name to fit Batch's event naming rules. - -For example, an event named `Ad Shown` will become `AD_SHOWN`. Note that this means that event names longer than 30 characters will be truncated. -The events `title` property will become the event's label. - -## Group - -When you call `group`, we will set the group ID in a user attribute named `SEGMENT_GROUP`. - -## Features - -All of our supported Segment integration features will work automatically, with no action or specific properties required on your side. - -Batch's other features are available directly by using the native SDK, which comes bundled with this integration. - -To use the Batch native SDK through Segment, follow the [instructions for Android](/docs/connections/sources/catalog/libraries/mobile/android/#how-can-i-use-a-destination-specific-feature) and [instructions for iOS](/docs/connections/sources/catalog/libraries/mobile/ios/#what-if-your-sdk-doesnt-support-feature-x). +{% include components/actions-fields.html %}