Parameters

Parameters list

Basic parameters

Id	Description
`name`	String - Min. 3 chars - Required Readable name of the campaign. E.g.`{"name":"My Engagement Campaign"}`
`live`	Boolean - 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}`
`labels`	Array 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.

Id	Description
`start_date`	String - 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_date`	String - 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_date`	String - 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_date`	String - 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

Id	Description
`trigger`	Object - Required An object describing when the In-App message will be triggered and displayed.
	`capping`	Integer - Optional The maximum number of time a given user can receive the In-App message E.g.`{"capping":1}`
	`priority`	String - Optional - A value among `STANDARD` , `IMPORTANT` and `CRITICAL` If multiple campaigns should be displayed at the same time, the priority determines which one to display before the others. `STANDARD` is the default and lowest priority, `IMPORTANT` has a higher priority and `CRITICAL` is the highest one. E.g.`{"priority":"CRITICAL"}`
	`grace_period`	Object - Optional See below section Grace period
	`when`	Object or String - Required See below section When

Grace period

The grace period avoids the In-App message to be displayed multiple times in a short time range.

Id	Description
`grace_period`	Object - Optional An object describing the grace period duration. E.g.`{"grace_period":{"every":2,"unit":"DAYS"}}`
	`every`	Integer - The grace period duration value E.g.`{"every":2}`
	`unit`	String - Required The grace period duration unit. Acceptable values include: `HOURS` and `DAY` E.g.`{"unit":"DAYS"}`

When

Id	Description
`when`	Object 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"}}`
	`event`	String - Required Event name. Custom events must be prefixed by 'e.'. E.g.`{"event":"e.event_name"}`
	`label`	String - Optional Even label E.g.`{"label":"event_label"}`

User targeting

Id	Description
`targeting`	Object - Optional An object containing the targeting property of the campaign. If omitted, all users will be targeted.
	`languages`	Array of Strings - An array containing all device languages to be targeted. All language codes in this array must be contained in the messages object. See here for matching rules and valid language codes. E.g.`{"languages":["it","fr"]}`
	`regions`	Array of Strings - An array containing all the geographical regions codes to be targeted. See here for all valid region codes. E.g.`{"regions":["FR","US"]}`
	`segments`	Array of Strings - An array containing the smart segments to be targeted. Acceptable values include: `NEW` , `ONE_TIME` , `ENGAGED` , `DORMANT` and `IMPORTED` . If you ommit this field or pass [], all users, included imported ones, will be targeted. E.g.`{"segments":["ENGAGED","NEW"]}`
	`query`	Object - A mongo inspired query object containing filters & operators, based on native attributes (app version, OS version, etc) and custom users data (attributes, tags & events defined by you in the SDK) .
	`custom_audiences`	Array of Strings - An array containing all the custom audiences that should be targeted.
	`just_in_time`	Boolean - Optional Whether the targeting should be checked right before displaying the landing message. If `true` , the SDK will check, before displaying the message, if the user matches the targeting. If `false` (the default), the targeting will be checked only when the campaign is sent.

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.

Id	Description
`theme`	String - Required The code of the theme to use for your landing view E.g.`{"theme":"dark_base_theme"}`
`tracking_id`	String - Optional A tracking ID that you will receive in your application if set E.g.`{"tracking_id":"OPEA20161005"}`
`contents`	Array of Objects - Required The contents of the landing message. See here for message localization rules and valid language codes.
	`language`	String - Required The language of the message E.g.`{"language":"en"}`
	`header`	String - Optional - Supports message personalization The text of the header E.g.`{"header":"News"}`
	`title`	String - Optional - Supports message personalization The text of the title E.g.`{"title":"Update to the latest version!"}`
	`body`	String - Optional - Supports message personalization The text of the body E.g.`{"body":"Lots of bug and security fixes"}`
	`image`	String - Optional - Supports message personalization The url of the image to use if the theme contains one E.g.`{"image":"https://static.batch.com/medias/img/landing-samples/fly.15569dd6.jpg"}`
	`image_description`	String - Optional The description of the image used for accessibility purposes E.g.`{"image_description":"Boeing 747"}`
	`actions`	Array of objects - Required A list of actions available in the landing message. The action object will be described further below

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.

Id	Description
`action`	String - 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"}`
`label`	String - Required The label of the call to action E.g.`{"label":"Show"}`
`args`	Object - 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 / Android.

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.

Id	Description
`b.os_version`	String - 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_version`	String - Your app version. The expected format is X.Y.Z. E.g.`{"b.app_version":"2.A.3"}`
`b.device_type`	String - The device type / model. The full list of Apple model names is available here and a list of all the Android devices supported by the PlayStore is available here . Make sure you choose a value in the `model` column. E.g.`{"b.device_type":"iPhone8,1"}`
`b.carrier_code`	Integer - 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_id`	Boolean - True if the user posesses a Custom User ID in our Userbase. E.g.`{"b.has_custom_id":true}`
`b.transaction_tracked`	Boolean - True if a transaction have been detected from the user. E.g.`{"b.transaction_tracked":true}`
`b.city_code`	Integer - 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_optin`	Boolean - 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 (iOS / Android) or using the Custom Data API.

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 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 :

{
  "targeting": {
    "query": {
      "c.city": {
        "$eq": "Paris"
      }
    }
  }
}

As explained above, $eq is the default so we can ommit it:

{
  "targeting": {
    "query": {
      "c.city": "Paris"
    }
  }
}

All users with app version 1.0.1

{
  "targeting": {
    "query": {
      "b.app_version": {
        "$gte": "1.0.1"
      }
    }
  }
}

Users who installed your app 1 day ago and use an iPhone 6.

{
  "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.

{
  "$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

{
  "$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:

{
  "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:

{
  "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.

Documentation > API > In-App Campaigns API