• iOS
  • Android
  • Windows
  • Web
  • Cordova
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • FAQ
  • API > In-App Campaigns API

    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
    An array containing the label codes 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"]}
    deeplinkString - Max. 255 chars - Optional
    A URL that points to a specific part of your app.
    custom_payloadString - must be valid JSON - Optional (only available on paid plans)
    A JSON string containing additional parameters that your application can handle when receiving messages if configured to do so. The only forbidden key is com.batch. Format is: {"x":"y"}

    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.
    cappingInteger - The maximum number of time a given user can receive the In-App message
    E.g.{"capping":1}
    grace_periodObject - See below section Grace period
    whenString - NOW or NEXT_SESSION
    E.g.{"when":"NEXT_SESSION"}

    Grace period

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

    IdDescription
    grace_periodObject - Object
    An object describing the grace period duration.
    E.g.{"grace_period":{"every":2,"unit":"DAYS"}}
    everyInteger - The grace period duration value
    E.g.{"every":2}
    unitString - The grace period duration unit. Acceptable values include: HOURS and DAY
    E.g.{"unit":"DAYS"}

    User targeting

    IdDescription
    targetingObject - Optional
    An object containing the targeting property of the campaign. If omitted, all users will be targeted.
    languagesArray 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 all valid language codes.
    E.g.{"languages":["it","fr"]}
    regionsArray 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"]}
    segmentsArray 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"]}
    queryObject - 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_audiencesArray of Strings - An array containing all the custom audiences that should 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"}
    imageString - Optional
    The url of the image to use if the theme contains one
    E.g.{"image":"https://d1v3v59tzaau1a.cloudfront.net/medias/img/landing-samples/fly.15569dd6.jpg"}
    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
    languageString - The language of the message
    E.g.{"language":"en"}
    headerString - The text of the header
    E.g.{"header":"News"}
    titleString - The text of the title
    E.g.{"title":"Update to the latest version!"}
    bodyString - The text of the body
    E.g.{"body":"Lots of bug and security fixes"}
    image_descriptionString - The description of the image used for accessibility purposes
    E.g.{"image_description":"Boeing 747"}
    actionsArray of objects - 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.

    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"}}

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

    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": "DAY"
        },
        "when": "NEXT_SESSION"
      },
      "landing": {
        "theme": "HELLO_THEME",
        "image": "https://batch-doc.s3.amazonaws.com/logo_batch_192.png",
        "contents": [
          {
            "language": "en",
            "header": "Welcome",
            "title": "Hello!",
            "body": "How is it going?",
            "actions": [
              {
                "label": "Continue",
                "action": "continue",
                "args": {
                  "id": "1054"
                }
              }
            ]
          },
          {
            "language": "fr",
            "header": "Bienvenue",
            "title": "Salut!",
            "body": "Comment ça va ?",
            "actions": [
              {
                "label": "Continuer",
                "action": "continue",
                "args": {
                  "id": "1054"
                }
              }
            ]
          }
        ]
      },
      "custom_payload": "{\"tag\":\"welcome_push\"}"
    }

    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.

    • The custom_payload here implies that the app being pushed to can handle a dictionary string of "tag" with a value of "welcome_push". These are not required but can be added if desired.