Using Campaign APIs

Prisma Campaigns provides several campaign-related APIs. The endpoints listed below allow developers to retrieve active campaigns for each client, show the banners and images in placeholders, view funnel steps, and even trigger campaigns based on business events.

Active campaigns

This API returns all the active campaigns of a given client. To use it, do the following:

The posted information format is an EDN object:

data = {
   :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
   :customer-id "5114932"
   :category "Sales"
   :group "Cars"
   :trail-id  "882252f3-fe70-4402-9195-639d8037f339"
}

Banners and popups

With this API, you can return the list of banners and images available in a given placeholder. Each page or screen can potentially include several banners (or at least a single popup). In any event, you will synchronize the app screen by invoking a single API. The response includes all the elements corresponding to that screen for the customer in question.

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
    :trail-id "882252f3-fe70-4402-9195-639d8037f339"
    :sync-popups true
    :page-location "http://my.domain/page"
    :placeholders [
        {:placeholder "id-placeholder1"}
        {:placeholder "id-placeholder2"}
    ]
}

"data": {
    "app-token": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932",
    "trail-id": "882252f3-fe70-4402-9195-639d8037f339",
    "sync-popups": "true",
    "page-location": "http://my.domain/page",
    "placeholders": [
        {"placeholder": "id-placeholder1"},
        {"placeholder": "id-placeholder2"}
    ]
}

The response is an EDN or JSON object with two sets of information:

1. Banners to display in each placeholder
2. Information about the popup to display (if applicable)

and has the following structure:

response = {
   :popup = {}
   :placeholders = [{} {}]
}

"response": {
   "popup": {},
   "placeholders": [{}, {}]
}

Popup

The information structure of a popup contains the following data:

popup = {
    :tracking-token
    :campaign
    :show-close
    :funnel
}

In order to display the funnel associated with this popup, you should use the API as follows: /api/campaigns/:campaign/funnel?d=:tracking-token&a=:app-token&t=:trail-id&popup=true

Placeholders

The placeholders attribute in the sync-page API response contains the list of banners to be displayed in each of the requested placeholders.

If a placeholder does not have any banners associated with it for a given client, the response will be empty.

The structure of the response for each placeholder is shown below:

placeholder = {
    :customer-id "5114932"
    :banners-list [{b1} {b2}]
    :is-popup false
    :popup-timeout 1000
    :transition-time 5000
    :width 800
    :height 600
}

Each object inside banners-list contains the details of a banner for that placeholder. In case there are more than one, it will be possible to display them in different formats (carousel mode, grid, etc).

banner-detail = {
    :banner {banner object}
    :funnel {funnel object}
}

Within the funnel object, there are properties related to the customer’s conversion process along with the data regarding the first funnel step.

Funnel steps

To obtain the steps defined for the funnel, you can use the advance-funnel API, which will return the steps (one by one) as the customer completes them.

If there are forks in the funnel, based on the data or other user parameters, the next step will be determined after the current action concludes. Thus, you must use the API to obtain the first funnel step when the customer becomes interested in the campaign, as well as the following steps as each one finishes.

The posted information format is an EDN or JSON object:

data = {
 :trail-id  "882252f3-fe70-4402-9195-639d8037f339"
 :campaign-id 123123101
 :tracking-token "12312-21919-j1b3-121m-1212"
 :step-data {}
}

"data": {
 "trail-id": "882252f3-fe70-4402-9195-639d8037f339",
 "campaign-id": "123123101",
 "tracking-token": "12312-21919-j1b3-121m-1212",
 "step-data": {}
}

The campaign-id and tracking-token parameters must match the interaction the user made. For example, if the user clicked on a banner, the campaign and tracking-token data corresponding to that banner should be included.

The step-data parameter should not be sent when the user starts the funnel. In all other cases, it is required (even if empty) to move to the next step.

The structure of the response is shown below:

response = {
  :type data-capture | message | redirect
  :config {}
}

The configuration detail for each step type is described below.

Message Step

step = {
 :title
 :message
 :actions
 :remaining-steps
 :max-steps
}

"step": {
 "title":
 "message":
 "actions":
 "remaining-steps":
 "max-steps":
}

Data capture

step = {
 :fields
 :actions
 :remaining-steps
 :max-steps
}

"step": {
 "fields":
 "actions":
 "remaining-steps":
 "max-steps":
}

where

The fields list indicates which fields the customer should fill out in this step, where each follows this structure:

field = {
  :label
  :name
  :control-type
  :value
}

"field": {
  "label":
  "name":
  "control-type":
  "value":
}

When you invoke the advance-funnel API, the step data must contain the values of the captured fields using name as a reference.

Redirect

The configuration detail for redirect steps is the following:

step = {
   :url
   :method
   :parameters
   :include-system-params
   :new-window
}

"step": {
   "url":
   "method":
   "parameters":
   "include-system-params":
   "new-window":
}

Customers

This endpoint allows you to create or update the information of a new or existing customer:

The format of the posted information is an EDN or JSON object:

data = {
 :customer {:id 12345
            :field "xxyyzz"}
 :app-token "882252f3-fe70-4402-9195-639d8037f339"
}

"data": {
 "customer": {"id": "12345",
            "field": "xxyyzz"},
 "app-token": "882252f3-fe70-4402-9195-639d8037f339"
}

The result is defined by one of the following HTTP status codes:

Business Events

Campaigns can be triggered based on certain business events that are particular for each company, and Prisma Campaigns provides a method to do so. Since business events only have meaning in the scope of an application, the administrator must configure the application that will potentially trigger them. To do this, go to Settings/Applications and create a new business event by entering a name (which must be unique) and a description.

Next, you can associate a business event with a campaign in the corresponding section of the campaign settings. By default, business events apply to all the customers in the segment, but you can also filter them if you need to.

To trigger a business event, send a POST request as follows:

The body of the request must contain the following data:

The server will return a 202 Accepted status in case of success or 404 Not Found if no matching campaign is found. Additionally, the response includes the following fields:

Note: The server may return an EDN or JSON object depending on the content of the Accept and Content-Type headers. It is worth noting that the latter is mandatory.

Related Articles

• Using Business Events