Integrate with Batch

Now that we have covered the basics of what integrations are, let's try and explore the technical details each integration might involve.

First of all, this doc aims at displaying the technical possibilities of partnership with Batch. Be advised that it is mostly based on our current connectors but as we are quite flexible on the format of these, make sure to get in touch with us if you want to connect your solution to ours. You can leave us a message on the live chat or via our partners@batch.com address, we will come back to you as soon as we can.

Be sure to take a look at our classic integration schemas before digging in, they provide a solid base of what integrations generally look like :

Types of integrations

There are two ways Batch can be connected to a new service. Data can be sent to Batch via an Inbound integration, or data can be sent from Batch to a third party solution via an Outbound integration.

Inbound integrations

Batch offers two main entrypoint for incoming data. Via its native SDK methods to collect custom data (iOS/Android), or via its extensive set of RESTful APIs. More specifically, Batch is capable to ingest:

Outbound integrations

During your workflow using Batch, a lot of data is being generated for targeting and campaign analytics purposes, some of which can be exported to any third-party service. Here are the data that are produced by Batch and able to be exported:

As export marked with * require a custom intervention from Batch's technical team, they may involve additional setup costs.

Inbound: sending push campaigns

Batch exposes two APIs in order to allow any third-party integration to send notification, provided that this third-party posesses the proper Batch API keys of the concerned app. We expose three different endpoints to allow our client and partners to operate push notifications :

  • The standard Transactional API, specifically designed for 1-to-few interactions,
  • The Partners Transactional API, allowing to send push notifications while keeping the content creation on Batch's dashboard,
  • The Campaigns API, specifically suited for 1-to-many interactions.

Using the standard Transactional API

Here's the documentation on how to use it. This API is more suited for 1-to-1 interactions rather than broad engagement with the userbase. You can use it to target a predefined list of users, targeted using push-tokens, Advertising IDs, Custom IDs or Batch Installation IDs.

This API is to be used for campaigns that involve a trigger event that is external to Batch, or campaigns that only target a restrain number of devices. Its use is very simple but advanced campaign analytics won't be available using this API.

Using the Partners Transactional API

Any use of the Transactional API would suggest that the third-party service which Batch will be connected to contains a campaign editor interface to compose the message. If building such an interface is not within the partner's range at the moment, we can also expose an additional feature for this API to keep the campaign edition on Batch dashboard.

This feature will make the message object optionnal, while requiring a new template_id string object in the call payload. This template_id will refer to the campaign token of a previously saved campaign from the dashboard. Campaign will be created on Batch then users will refer to them on the partner's interface to associate content with a campaign.

templateid

Two ways of getting that template_id on the partner's interface :

  • Either by copy-pasting the template_id from Batch's campaign editor URL as follow : https://dashboard.batch.com/<COMPANY_ID>/apps/<APP_ID>/campaigns/CAMPAIGN_TOKEN`.
  • Either by fetching all available draft campaigns and proposing them to the client. This endpoint of the Campaigns API will provide the list of all campaigns, with their campaign_token and name for client comprehension.

Here is what a minimal payload looks like with this template ID :

{
  "recipients": {
    "custom_ids": ["USER_CUSTOM_ID"]
  },
  "template_id": "CAMPAIGN_TOKEN"
}

Note that all standard Transactional API fields but recipients become optional with this new API. Adding more fields in the payload, such as group-id, message, deeplink or media will overwrite the campaign content data linked to this specified template_id.

This API feature requires manual activation on our end, contact us to know more: partners@batch.com

Using the Campaigns API

As you can see in the documentation of this API, there are two main ways of managing targeting. You can use the Batch powerful segmentation engine and you can target audiences that have been previously uploaded to Batch (these two methods can be combined).

The second option is particularly useful if your third-party service already includes a segmentation feature:

  1. First the segment or audience has to be uploaded to Batch via the Custom Audience API or the dedicated interface in Batch dashboard in the Settings > Audience section (Audience in the form of a monocolumn .CSV of Advertising IDs or Custom IDs can be manually uploaded),
  2. A call to the campaigns API can be made targeting the uploaded audience within the targeting object (documentation).

Althought looking similar to using the Transactional API, this last option offers the advantage of creating real campaign objects on Batch side, hence enables advanced campaign analytics and re-usable templates.

You can also leave the message edition part on Batch dashboard by creating a draft campaign with this API (attribute live: false). Users will then be free to complete it before it is sent, via the dashboard or an ultimate update API Call (attribute live: true).

Inbound: sending user data & segmentation

Using APIs

The Custom Data API and the Custom Audience API respectively allow third-party services to send raw user data and user segments. Raw user data will be directly available on Batch as Custom Attributes, while user segments will be available as Custom Audiences. The documentation will give you all the details about their use.

Ingesting segments via flat-files

Alternatively, if a third-party service can't use the Custom Audience API to send Batch segmentation, Batch can upload flat files Audiences from a space storage. A script will be set up to automatically ingest those deposits to retrieve them as Custom Audiences on Batch dashboard. Flat-files can be ingested from a S3 bucket, SFTP, FTP, FTPS and webservices.

Here is a list of what we need to set this type of import:

  • How should we access to the segment file?
  • How should we name the Audience according to the flat-file information?
  • Does the file have a header (firstline) ?
  • How is the flat-file constructed? What are the columns and delimiter?
  • How is a user identified in the segment? We accept Advertising IDs (IDFA/GAID) or Custom User IDs.
  • Is the filename handled while uploading?
  • Ideally, Batch would delete the flat-file after ingestion.
  • Should we expect changes on the files from your side (eg: lines added / removed, file being reuploaded etc.)? If so, can we consider that previously added audience/campaign should be removed?

Get in touch with us for this solution as it implies a manual intervention from our technical team.

Clientside integration

As for an integration SDK-2-SDK to send Batch user attribute & events data, get in touch with us and our partnership team will quickly come back to you to work hand-in-hand on an integration.

Batch can send a daily .CSV export of the push related raw events that have occurred during the last UTC day per app with on each line, a user ID, a timestamp and the associated event. The resulting flat file can be dropped on any storage service including AWS S3, FTP, SFTP or FTPS. All events are UTC dated, and the export is generated after each UTC day + 2h.

Here is an example of .CSV export that we could send:

CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T00:00:00;push_sent;campaign;CAMPAIGN_TOKEN;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;push_opened;campaign;CAMPAIGN_TOKEN;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;push_error;campaign;CAMPAIGN_TOKEN;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;push_sent;transactional;TRANSACTIONAL_TOKEN;GROUP-ID
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;push_error;transactional;TRANSACTIONAL_TOKEN;GROUP-ID
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;push_opened;transactional;TRANSACTIONAL_TOKEN;GROUP-ID
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;push_optin;;;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T11:00:00;token_deleted;;;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T10:00:00;push_optout;;;

The campaign token corresponds to the response token that is sent after a successfull call to the Campaigns API. It can be used to fetch campaigns content and statistics from this API.

Similarly, the Transactional token is the response token after a successfull call to the Transactional API. These tokens allow third-parties to link the events to the campaign they sent.

These exports can be adapted to your own needs, replacing Installation IDs by Advertising IDs for instance.

As you can see, there are 6 types of different events:

  • push_optin: triggered when a user subscribes to notifications,
  • push_optout: triggered when a user unsubscribes from notifications,
  • push_sent: triggered when a notification is sent to a user,
  • push_opened: triggered when a user open a notification,
  • push_error: triggered when APNs or FCM states an error when trying to send a push notification,
  • token_deleted: triggered when Batch tries to send a push to a token invalidated by APNs or FCM (often when the app have been uninstalled).

As for the naming of the files, it would follow this nomenclature:

  • APPNAME-events_BATCH-API-KEY@IOS_YYYY-MM-DD.csv
  • APPNAME-events_BATCH-API-KEY@ANDROID_YYYY-MM-DD.csv

Quite similarly to the push related event export, Batch can send a daily .CSV export of the raw events related to In-App messages that have occurred during the last UTC day per app. The resulting flat file can be dropped on any storage service including AWS S3, FTP, SFTP or FTPS. All events are UTC dated, and the export is generated after each UTC day + 2h.

And a sample of generated file would be:

user_id;identifier;date_event;event_type;event_var_1;event_var_2;event_var_3
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;inapp_supplied;CAMPAIGN_TOKEN;;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;inapp_shown;CAMPAIGN_TOKEN;;
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;inapp_clicked;CAMPAIGN_TOKEN;0;batch.CustomAction
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;inapp_clicked;CAMPAIGN_TOKEN;1;batch.deeplink
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;inapp_clicked;CAMPAIGN_TOKEN;1;batch.dismiss
CUSTOM_USER_ID;BATCH_INSTALLATION_ID;2017-07-24T09:00:00;inapp_closed;CAMPAIGN_TOKEN;;

Events are generated as follows:

  • inapp_supplied: triggered upon downloading the In-App message if the device is subscribed to the campaign,
  • inapp_shown: triggered upon In-App message display on the device’s screen,
  • inapp_clicked: triggered upon user’s interactions with the In-App message CTAs,
  • inapp_closed: triggered when the user closes the In-App message, either with the close button (top screen cross icon), or the back button on Android.

event_var_1 is the campaign ID, event_var_2 is the position of the clicked CTA and event_var_3 is the content of the clicked CTA button

The campaign token corresponds to the response token that is sent after a successfull call to the In-App Campaigns API. It can be used to fetch the campaign content.

As for the naming of the files, it would follow this nomenclature:

  • APPNAME-InAppevents_BATCH-API-KEY@IOS_YYYY-MM-DD.csv
  • APPNAME-InAppevents_BATCH-API-KEY@ANDROID_YYYY-MM-DD.csv

Outbound: opt-in users export

If you are using Batch APIs in order to send notifications to your users, then you might want to know which one is opt-in to push notifications and who isn't. In any cases, people who are not opt-in to notifications won't receive them, but this export will let you know who will actually see them on screen for analytics purposes.

Similarly to the event export, the resulting .CSV flat file can be dropped on any storage service including GCP, AWS S3, FTP, SFTP or FTPS, after each UTC day + 2h.

It would be named as such:

  • APPNAME-userbase_BATCH-API-KEY@IOS_YYYY-MM-DD.csv
  • APPNAME-userbase_BATCH-API-KEY@ANDROID_YYYY-MM-DD.csv

And the format would be the following:

CUSTOM_USER_ID1;ADVERTISING_ID1;True
CUSTOM_USER_ID1;ADVERTISING_ID2;True
CUSTOM_USER_ID3;ADVERTISING_ID3;False
CUSTOM_USER_ID4;ADVERTISING_ID4;True
CUSTOM_USER_ID5;ADVERTISING_ID5;False
;ADVERTISING_ID6;False
...

Since a user can be logged with the same account on multiple devices, multiple Advertising IDs can be attributed to the same Custom User ID. Furthermore if a user is browsing your app anonymously, no Custom User ID at all could be attributed to an Advertising ID.

This opt-in settings refers to the iPhone settings on iOS and the custom settings on Android if it has been manually implemented (see here for more info). Thematic & custom optins should be collected outside of Batch simultaneously in order to send push notifications accordingly.