Coming soon: Landing Framework - White label marketing for agencies.

Documentation

Pulse Platform

Pulse Platform API

This document describes how to use the Pulse Platform Scenario Board API for use with apps. An app can post a url or code to the Pulse Platform API and retrieve all data related to this url. This url can point to a mobile site or landing page created with the proximity platform. The retrieved data consists of beacons, geofences and scenarios with various types of content.

Overview scenario board scenario management

Endpoint

The API endpoint is https://demo.pulseplatform.io (or wherever you've installed the platform).

All API responses are in JSON format.

Retrieve scenario board scenarios

Workflow

The app posts the url or code to the proximity platform API. If the url or code is recognized as a mobile site or landing page in the system, all scenario board related information is returned. A JSON response as seen below is returned.

The app will load the content.url in its web view. For precise statistics, the app can add the following GET parameters to the web view: ?src=app&lat=[latitude]&lng=[longitude].

{
  ...
  "content": {
    "found": true,
    "type": "app",
    "name": "API App",
    "url": "https://demo.pulseplatform.io/mobile/api-test"
  }
}

Scenario board endpoint

Endpoint: /api/v1/remote/handshake
Method: POST

Input

Parameter Value
url required, FQDN or code *
uuid required, UUID of device
model optional, device model
platform optional, device platform (Android, iOS)
lat optional, latitude of device
lng optional, longitude of device

* A code is the last part of a mobile site or landing page url created with the proximity platform. If the url is https://demo.pulseplatform.io/mobile/discount001, the code is discount001. It's case insensitive so DISCOUNT001 will also work. Codes can be entered at Apps > Select App > Options > App settings > Domain.

Response

The API checks if the url exists in the system. A url can be related to a mobile site or landing page and a url can be a FQDN or a code.

Nothing was found

If the url isn't found in the system, the following JSON is returned:

{
  "content": {
    "found": false,
    "type": null,
    "name": [host|code],
    "icon": null
  }
}

[host|code] is either the hostname of the FQDN or the code that was posted. For example, if the input was https://example.com and this url wasn't recognized as an existing url in the system, content.name will return example.com.

Url found, no scenarios

If the url is found but no scenario boards or active scenarios are linked to it, JSON like below is returned. Geofences have a radius in meters. content.type can be app or site.

{
  "board": null,
  "geofences": [],
  "beacons": [],
  "scenarios": [],
  "content": {
    "found": true,
    "type": "app",
    "name": "API App",
    "url": "https://demo.pulseplatform.io/mobile/api-test",
    "icon": "https://demo.pulseplatform.io/static/app-icons/store/120.png"
  }
}
Url and scenarios found

If the url and related scenarios are found, the JSON looks like this:

{
  "board": {
    "timezone": "UTC"
  },
  "geofences": [
    {
      "id": 1,
      "identifier": "Region 1",
      "lat": "51.57543589739877",
      "lng": "5.370797920227051",
      "radius": 25
    }
  ],
  "beacons": [
    {
      "id": 2,
      "identifier": "Beacon 1",
      "uuid": "e9cee965-27b8-a146-7b01-4ccce97f23b2",
      "major": 1,
      "minor": 2
    },
    {
      "id": 3,
      "identifier": "Beacon 2",
      "uuid": "e9cee965-27b8-a146-7b01-4ccce97f23b2",
      "major": 1,
      "minor": 3
    }
  ],
  "scenarios": [
    {
      "id": 2,
      "app_id": 2,
      "site_id": null,
      "id": 2,
      "scenario_if_id": 1,
      "scenario_then_id": 2,
      "scenario_day_id": 2,
      "scenario_time_id": 2,
      "time_start": null,
      "time_end": null,
      "date_start": "2016-02-01",
      "date_end": "2016-12-01",
      "frequency": 0,
      "delay": 2,
      "notification": "Push notification text",
      "show_image": null,
      "template": null,
      "open_url": null,
      "play_sound": null,
      "play_video": null,
      "add_points": null,
      "substract_points": null,
      "settings": null,
      "geofences": [
        1
      ],
      "beacons": [
        2
      ]
    },
    {
      "id": 3,
      "app_id": 2,
      "site_id": null,
      "scenario_if_id": 3,
      "scenario_then_id": 3,
      "scenario_day_id": 1,
      "scenario_time_id": 1,
      "time_start": null,
      "time_end": null,
      "date_start": null,
      "date_end": null,
      "frequency": 0,
      "delay": 2,
      "notification": null,
      "show_image": null,
      "template": "https://demo.pulseplatform.io/api/v1/remote/template/eyJpdiI6Ikc3T0lxV2ZSNVNPUWgwZm1RME5UclE9PSIsInZhbHVlIjoibFNcL3F1SG5RUWtjZWZyVFlZR1h4R2JkQ3BVRFFiU1hzMHRSWERXQmQ2bGM9IiwibWFjIjoiNzFiMWRkZmE1OGQzMWY0Y2QwMmI2YWMwNWI3YjI1MDI1M2U3NzJiZDM1Zjg3NzNkMDAzODdjMDhmZjI2OGU2MyJ9",
      "open_url": null,
      "play_sound": null,
      "play_video": null,
      "add_points": null,
      "substract_points": null,
      "settings": null,
      "geofences": [],
      "beacons": [
        3
      ]
    }
  ],
  "content": {
    "found": true,
    "type": "app",
    "name": "API App",
    "url": "https://demo.pulseplatform.io/mobile/api-test",
    "icon": "https://demo.pulseplatform.io/static/app-icons/store/120.png"
  }
}

Scenario values

id

Integer, unique scenario id. Can be used for internal reference in the app.

app_id

Integer, unique app id. The app that triggered the scenario. If null, site_id is set.

site_id

Integer, unique site id. The site that triggered the scenario. If null, app_id is set.

scenario_if_id

Integer.

Id Value
1 enters_region_of
2 exits_region_of
3 is_far_from
4 is_near
5 is_very_near
scenario_then_id

Integer.

Id Value
1 do_nothing
2 show_image
3 show_template
4 open_url
12 show_app
13 show_site
scenario_day_id

Integer, if id is 2 then date_start and date_end are used.

Id Value
1 every_day
2 between_two_dates (date_start and date_end)
3 saturday_and_sunday
4 friday_and_saturday
5 monday_to_friday
6 sunday_to_thursday
7 monday
8 tuesday
9 wednesday
10 thursday
11 friday
12 saturday
13 sunday
scenario_time_id

Integer, if id is 2 then time_start and time_end are used.

Id Value
1 all_the_time
2 between_two_times
time_start

Time format HH:MM:SS in board timezone. Only used when scenario_time_id is 2. Seconds are always 00.

time_end

Time format HH:MM:SS in board timezone. Only used when scenario_time_id is 2. Seconds are always 00.

date_start

Date format YYYY:MM:DD in board timezone. Only used when scenario_day_id is 2.

date_end

Date format YYYY:MM:DD in board timezone. Only used when scenario_day_id is 2.

frequency

Integer. Amount of seconds that must pass in order to retrigger this scenario. If 0, this scenario is only triggered once until the user has been out of the region of the beacon or geofence.

delay

Integer. Amount of seconds before scenario is triggered, given the region hasn't changed.

notification

String. Text used for push notification. Only used when scenario_if_id is 1 or 2. This is because beacons and geofences can be monitored in the background when an app is closed. This push notification opens the app and triggers the rest of the scenario. Geofences can only use scenario_if_id 1 or 2 because they don't have a proximity parameter like beacons.

show_image

Url. Only used when scenario_then_id is 2.

show_template

Url. Only used when scenario_then_id is 3. This url can be opened in the web view of the app.

open_url

Url. Only used when scenario_then_id is 4, 12 or 13. This url can be opened in the web view of the app.

geofences

Array with integers. The list of geofences used with this scenario. The integers refer to geofences[n].id.

beacons

Array with integers. The list of beacons used with this scenario. The integers refer to beacons[n].id.

Example

curl -i -X POST \
   -d "url=https://demo.pulseplatform.io/mobile/tour360" \
 'https://demo.pulseplatform.io/api/v1/remote/handshake'