Parameters

Parameters list

Basic parameters

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.

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

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.

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

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

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

lean - 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.

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

webview_url

String - Required, WebView theme only URL that WebView format should display

link_open_target

String - Required, WebView theme only

Valid values: IN_APP, BROWSER

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.

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.

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

PreviousGET - View In-App campaign NextCustom Audience

Last updated 13 days ago

Was this helpful?