# Parameters ### Parameters list #### Basic parameters
IdDescription
nameString - Min. 3 chars - Required
Readable name of the campaign.
E.g.{"name":"My Engagement Campaign"}
liveBoolean - Required
Value that sets the campaign to live. A false value will save the campaign as a draft but not activate it
E.g.{"live":true}
labelsArray of Strings - Optional - Max. 3 labels
An array containing the label names you want to attach to your campaign. You can use labels to filter the list of campaigns that appears on Batch's dashboard. Notice that related cappings are only applied to push Campaigns, but not on In-App Campaigns.
E.g.{"labels":["label1","label2"]}
#### Timing and delivery Two timezone parameters can be specified: `start_date` and `end_date`, and their counterparts `local_start_date` and `local_end_date`. If none of these parameters are specified, the In-App campaign will start now without any end date.
IdDescription
start_dateString - Optional - Conflicts with local_start_date
Time that the In-App campaign will be activated GMT (UTC+0000). Format is yyyy-MM-ddTHH:mm:ss or now to activate the campaign immediately.
E.g.{"local_start_date":"2015-12-01T14:25:00"}
local_start_dateString - Optional - Conflicts with push_time
A value that defines the campaign activation time in terms of the user's device. The In-App campaign will be activated at the selected time for each time zone.
Format is yyyy-MM-ddTHH:mm:ss
E.g.{"local_start_date":"2015-12-01T14:25:00"}
end_dateString - Optional - Conflicts with local_end_date
Time that the In-App campaign will end GMT (UTC+0000). Format is yyyy-MM-ddTHH:mm:ss .
E.g.{"end_date":"2015-12-01T14:25:00"}
local_end_dateString - Optional - Conflicts with end_date
A value that defines the campaign end time in terms of the user's device. The In-App campaign will end at the selected time for each time zone.
Format is yyyy-MM-ddTHH:mm:ss
E.g.{"local_end_date":"2015-12-01T14:25:00"}
#### Trigger
IdDescription
triggerObject - Required
An object describing when the In-App message will be triggered and displayed.
**Grace period** The grace period avoids the In-App message to be displayed multiple times in a short time range.
IdDescription
grace_periodObject - Optional
An object describing the grace period duration.
E.g.{"grace_period":{"every":2,"unit":"DAYS"}}
**When**
IdDescription
whenObject or String - Optional
A string ( NOW or NEXT_SESSION ) or an object (if the trigger is an event) describing when the In-App message should be triggered.
E.g.{"when":{"event":"e.event_name","label":"event_label"}}
#### User targeting
IdDescription
targetingObject - Optional
An object containing the targeting property of the campaign. If omitted, all users will be targeted.
#### Landing message This will display a landing view using the theme and content of your choosing, allowing you to have complex interactions. The landing message is defined under the `landing` key at the root of the payload and the following fields are allowed.
IdDescription
themeString - Required
The code of the theme to use for your landing view
E.g.{"theme":"dark_base_theme"}
tracking_idString - Optional
A tracking ID that you will receive in your application if set
E.g.{"tracking_id":"OPEA20161005"}
contentsArray of Objects - Required
The contents of the landing message. See here for message localization rules and valid language codes.
> **Note**\ > If your theme contains the close button, the `actions` array is not strictly required. **The action object** Each action in the landing message must be defined as follows.
IdDescription
actionString - Required
The action name. Must match with the actions you register in your mobile application. Not strictly required, if null the close action will be used
E.g.{"action":"show_article"}
labelString - Required
The label of the call to action
E.g.{"label":"Show"}
argsObject - Optional
An object containing arbitrary data that will be passed to your action as is
E.g.{"args":{"id":4,"category":"sports"}}
> **Important note**: You will find here a list of all the built-in actions you can use in your Mobile Landing to dismiss the In-App message, use a deeplink, and more : [iOS](https://doc.batch.com/developer/sdk/ios/advanced/custom-actions#built-in-actions) / [Android](https://doc.batch.com/developer/sdk/android/advanced/custom-actions#built-in-actions). ### The query object For advanced usage, you can pass a query object to the targeting. This is a homemade syntax, inspired by MongoDB. This feature is available to **Pro** and **Enterprise** users for **native** and **custom** attributes. #### Native attributes Native attributes allow you to target users based on their OS and app version, their device type or the number of days since they installed your app. Native attributes must be added in `query`, as a `targeting` property.
IdDescription
b.os_versionString -
The Android or iOS version.The expected format is X.Y.Z. The OS version cannot contain any letter.
E.g.{"b.os_version":"5.1.1"}
b.app_versionString -
Your app version. The expected format is X.Y.Z.
E.g.{"b.app_version":"2.A.3"}
b.device_typeString -
The device type / model. Make sure you choose a value in the model column.
E.g.{"b.device_type":"iPhone8,1"}
b.carrier_codeInteger -
Your user's carrier. The code provided by Batch is a combination of the Mobile country code (MCC) and the Mobile network code (MNC) . The full list of MCC and MNC codes is available here . Not supported on iOS 16.4 and higher.
E.g.{"b.carrier_code":20815}
age(b.install_date)Duration -
Number of days elapsed since the install (install: the first time Batch SDK sees the user) . The days are counted in sections of 24 hours from the hour of install.
E.g.{"age(b.install_date)":1}
age(b.last_visit_date)Duration -
Number of days elapsed since your users' last session. The days are counted in sections of 24 hours from the last session.
E.g.{"age(b.install_date)":1}
b.has_custom_idBoolean -
True if the user posesses a Custom User ID in our Userbase.
E.g.{"b.has_custom_id":true}
b.transaction_trackedBoolean -
True if a transaction have been detected from the user.
E.g.{"b.transaction_tracked":true}
b.city_codeInteger -
You user's city detected by Batch using IP geolocation.
E.g.{"b.city_code":2988507}
age(b.last_push_date)Duration -
Number of days elapsed since the last time you sent your user a push via the dashboard or the Campaigns API.
E.g.{"age(b.last_push_date)":2}
isNear(int latitude, int longitude, string radius, duration time)Boolean -
True if the last collected user's location is within the given radius around the coordinates during the last X hours. Batch SDK must be allowed to collect geolocation to enable this query.
E.g.{"isNear(48.8407578796295,2.351546582031233,5000m,12h)":true}
b.is_push_optinBoolean -
True if the install is opt-in to push, meaning that it can receive and display push notifications.
E.g.{"b.is_push_optin":false}
By default, a `Duration` object is an Integer that represents a number of days. This object can be in any other time unit if it is given a String with the value and the unit. For instance `"12h"` represents a number of hours. *E.g.*`{"age(b.last_push_date)": “12h”}` Instead of `age()`, you can also use `date()` on date attributes. This function will return a UTC timestamp Integer. > **RECOMMENDED**
* Users coming from an older version of your app and upgrading to a version with Batch's SDK *(after a first release or a token import)* are considered as new installs.
* If you are planning to use this attribute to send 1-3-7 days post-install notifications, we recommend that you wait at least 7 days to make sure you only target your new users. #### Custom user data You can send custom user data from your app or using the [Custom Data API](https://doc.batch.com/developer/api/mep/custom-data-api/set-update). **Attributes** Custom attributes are prefixed with `c.` or `u.` if they are sent from the Custom Data API, and are simple key/value data. You can use them to collect a: * String * Number / Decimal * Boolean * Date **Tags collections** Tags are prefixed with `t.` or `ut.` if they are sent from the Custom Data API, and are sets of tags. **Events** Events are prefixed with `e.` and have a key, an occurence date, an optional label, and an optional data object. > **Recommended**\ > Take a look at [this guide](https://github.com/BatchLabs/product.tech-documentation-gitbook/blob/master/guides/custom-data/README.md) to know more on custom data and learn how to tag your app. #### Operators * `$eq` Equal to. This is the default and thus can be ommited. * `$lt` Lower than < * `$lte` Lower or equal than <= * `$gt` Greater than > * `$gte` Greater or equal than > * `$contains` Checks if the tag collection has one of the requested tag * `$containsAll` Checks if the tag collection has all of the requested tag **Basic examples** Targets to all users who live in Paris : ```json { "targeting": { "query": { "c.city": { "$eq": "Paris" } } } } ``` As explained above, $eq is the default so we can ommit it: ```json { "targeting": { "query": { "c.city": "Paris" } } } ``` All users with app version 1.0.1 ```json { "targeting": { "query": { "b.app_version": { "$gte": "1.0.1" } } } } ``` Users who installed your app 1 day ago and use an iPhone 6. ```json { "targeting": { "query": { "$and": [ { "age(b.install_date)": 1 }, { "b.device_type": { "$gt": "iPhone7,2" } } ] } } } ``` When you need multiple conditions, the first level of your query needs to be an `$and`, with an array of conditions. #### Functions and advanced example Date attribute needs a function to be queried; that's why we showed you `age(b.install_date)` before. We plan to introduce more functions to our API to enable events querying in the upcoming weeks. From now on, we will only show the query. Just remember it goes in `targeting.query`. *Users intersted by Rugby or Football, who installed in the last 10 days, and subscribed to your paid offer.* ```json { "$and": [ { "t.interest": { "$contains": ["Rugby", "Football"] } }, { "age(b.install_date)": { "$lte": 10 } }, { "c.paidSubscriber": true } ] } ``` *Users who installed your app since at least 10 days, living in Paris, at least Android 5.0, using the version 3.1.1 of your app, and subscribed to both France & Sport categories* ```json { "$and": [ { "age(b.install_date)": { "$gte": 10 } }, { "c.city": "Paris" }, { "b.os_version": { "$gte": "5.0" } }, { "b.app_version": "3.1.1" }, { "t.push_optin": { "$containsAll": ["France", "Sport"] } } ] } ``` > Please note that the **Imported** segment won't be selected if you target users based on custom user data (attributes, tags or events). ### cURL example Here is an example of a valid cURL CLI request syntax: ``` curl -H "Content-Type: application/json" -H "X-Authorization: BATCH-PUSH-API-TOKEN" -X POST -d "@payload.json" "https://api.batch.com/API_VERSION_NUMBER/BATCH_API_KEY/in-app-campaigns/create" ``` where `payload.json`: ```json { "name": "Test Campaign", "local_start_date": "2017-06-01T14:00:00", "live": true, "targeting": { "languages": ["it"], "regions": ["FR", "US"], "segments": ["ONE_TIME", "ENGAGED", "NEW"], "query": { "age(b.install_date)": 1 } }, "trigger": { "capping": 3, "grace_period": { "every": 1, "unit": "DAYS" }, "when": "NEXT_SESSION" }, "landing": { "theme": "HELLO_THEME", "contents": [ { "language": "en", "header": "Welcome", "title": "Hello!", "body": "How is it going?", "image": "https://static.batch.com/documentation/logo_batch_192.png", "actions": [ { "label": "Continue", "action": "continue", "args": { "id": "1054" } } ] }, { "language": "fr", "header": "Bienvenue", "title": "Salut!", "body": "Comment ça va ?", "image": "https://static.batch.com/documentation/logo_batch_192.png", "actions": [ { "label": "Continuer", "action": "continue", "args": { "id": "1054" } } ] } ] } } ``` The above example will start a recurring campaign on *June 1, 2015 at 14:00 (2PM)*, sending to users based on their device time. * It is set as `"live": true` so will begin at the designated time, versus resting as a draft requiring further action before sending. * The optional `targeting` object has been included to specify the device language, region, and targeted segments. If this object were not included, all users would be targeted. In this case, we used the native attribute `age(b.install_date)` to target users who installed the app one day ago. * Within the `landing` object each targeted language has been given a message. It's worth noting that you must have a message object for the default language of your app, as set within the Batch dashboard. * This campaign `trigger` here means that : * The message will be display 3 times to each user at the most * The message cannot be displayed more than one time in one day (24h) * The message will be displayed at the next session. It means that once the message is received by the device, it will be displayed the next time the user will open the app. * This campaign uses the `recurrence` optional object to have the campaign repeat *every day* at the originally defined time of *14:00* until *June 6, 2015* at *00:00*. ### A/B Testing A/B tested campaigns work a little bit differently than standard ones. #### Landings You can A/B test your landing message. To do that, you simply need to define two keys `a` and `b` under the `landing` key. Each key must contain a valid landing message object, as described above. Here's a quick example of an A/B tested in-app campaign: ```json { "landing": { "a": { "theme": "my-theme-1", "contents": [ { "language": "fr", "title": "Salut!", "body": "Comment vas-tu?", "actions": [ { "action": "batch.dismiss", "args": {}, "label": "Annuler" }, { "action": "batch.deeplink", "args": { "l": "https://google.fr/" }, "label": "Rechercher" } ] }, { "language": "en", "title": "Hey!", "body": "How are you?", "actions": [ { "action": "batch.dismiss", "args": {}, "label": "Cancel" }, { "action": "batch.deeplink", "args": { "l": "https://google.com/" }, "label": "Search" } ] } ] }, "b": { "theme": "my-theme-2", "contents": [ { "language": "fr", "title": "Bonjour!", "body": "Tu vas bien?", "image": "https://mydomain.com/myimage-1.png", "actions": [ { "action": "batch.dismiss", "args": {}, "label": "Annuler" }, { "action": "batch.deeplink", "args": { "l": "https://google.fr/" }, "label": "Rechercher" } ] }, { "language": "en", "title": "Hi!", "body": "How is it going?", "image": "https://mydomain.com/myimage-2.png", "actions": [ { "action": "batch.dismiss", "args": {}, "label": "Cancel" }, { "action": "batch.deeplink", "args": { "l": "https://google.com/" }, "label": "Search" } ] } ] } } } ``` > **Note**\ > Custom Payloads are not A/B testable.