Live API
This API is an add-on feature of Notificare. It can be used by other systems to get notified about almost everything in your application. From device registration, user data changes, geo-triggers and notifications sent in real-time. Build complex integrations of Notificare that react to users behaviour and other app events using your own infrastructure. Please contact sales@notifica.re to find out the pricing for your current plan.
Configure Service
Before you can use this API, please make sure you read and configure your app as described here.
After successful configuration and activation of this API, you will start receiving Live API events as described below. Note that any change to the Target Endpoint will reset the public and private keys and therefore you will need to repeat the whole process again.
Example Projects
For a hands-on approach, we've created some example projects to help you understand how you would set up your server and handle all the events streamed by this API. Please checkout these examples:
LIVE API Events
Below you will find a list of all the events available for you. Live API events are based in Notificare namespaces. The data received will be always directly connected to the type of event and should be handled accordingly.
Events
Sent whenever a public event is created. Only events over notifications received and opened, regions and beacons visits, passes added, removed or redeemed, as well as your own custom events are sent to this API.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.event.notification.Received | The events Notificare's namespace | String |
| data | {"id": "54ac46e8...2e39ca0", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.event.notification.Received |
| re.notifica.event.notification.Open |
| re.notifica.event.region.Session |
| re.notifica.event.beacon.Session |
| re.notifica.event.asset.Load |
| re.notifica.event.scannable.Scan |
| re.notifica.event.pass.Add |
| re.notifica.event.pass.Remove |
| re.notifica.event.pass.Redeem |
| re.notifica.event.custom.* |
Payload
| Key | Description |
|---|
| id | The Id of the event executed |
| region | The Id of the region (optional) |
| beacon | The Id of the beacon (optional) |
| serial | The serial of the pass (optional) |
| pass | The Id of the pass (optional) |
| notification | The Id of the notification (optional) |
| deviceID | The device where it was executed |
| userID | The user profile corresponding to that device |
Geo-Triggers
Sent whenever a geo-trigger is executed. Geo-triggers can be created based on a region or beacon.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.trigger.region.Enter | The geo-triggers Notificare's namespace | String |
| data | {"id": "54ac46e8...2e39ca0", "source": "54ac46e8...2e39ca0", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.trigger.region.Enter |
| re.notifica.trigger.region.Exit |
| re.notifica.trigger.beacon.Enter |
| re.notifica.trigger.beacon.Exit |
Payload
| Key | Description |
|---|
| id | The Id of the geo-trigger executed |
| source | The Id of the region or beacon |
| deviceID | The device where it was executed |
| userID | The user profile corresponding to that device |
Products
Sent whenever a product is purchased. Only applicable if you are using the Monetize add-on.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.reply.Receive | The purchases Notificare's namespace | String |
| data | {"id": "54ac46e8...2e39ca0", "identifier": "com.example.app.prod", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.product.Buy |
Payload
| Key | Description |
|---|
| id | The Id of the purchase |
| identifier | The product's SKU identifier |
| deviceID | The device where it was executed |
| userID | The user profile corresponding to that device |
Replies
Sent whenever a user replies to an actionable notification.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.trigger.region.Enter | The replies Notificare's namespace | String |
| data | {"id": "54ac46e8...2e39ca0", "notification": "54ac46e8...2e39ca0", "deviceID": "09260d8b1de06...948c516a", "userID": "support@notifica.re"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.reply.Receive |
Payload
| Key | Description |
|---|
| id | The Id of the reply executed |
| notification | The Id of the notification that was replied to |
| deviceID | The device where it was executed |
| userID | The user profile corresponding to that device |
Users
Sent whenever a user profile changes. This includes changes to user data, segments or devices.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.user.Register | The users Notificare's namespace | String |
| data | {"segment": "54ac46e8...2e39ca0", "userID": "support@notifica.re"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.user.Register |
| re.notifica.user.Create (only if Users & Authentication is available) |
| re.notifica.user.Validate (only if Users & Authentication is available) |
| re.notifica.user.AddDevice |
| re.notifica.user.RemoveDevice |
| re.notifica.user.Deactivate |
| re.notifica.user.Reactivate |
| re.notifica.user.AddSegment |
| re.notifica.user.RemoveSegment |
| re.notifica.user.LocationUpdate |
Payload
| Key | Description |
|---|
| segment | The Id of a segment (optional) |
| location | GeoJSON point (optional) |
| deviceID | The device where it was executed |
| userID | The user profile corresponding to that device |
Devices
Sent whenever device properties changes. This includes changes to tags.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.device.AddTag | The devices Notificare's namespace | String |
| data | {"tag": "tag_example", "deviceID": "09260d8b1de06...948c516a"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.device.AddTag |
| re.notifica.device.RemoveTag |
Payload
| Key | Description |
|---|
| tag | The name of the tag |
| deviceID | The device where it was executed |
Import
Sent whenever an import job changes status.
| Property | Example | Description | Type |
|---|
| service | My Service | The human readable string that describes this Live API service | String |
| type | re.notifica.import.Imported | The jobs Notificare's namespace | String |
| data | {"id": "54ac46e8...2e39ca0"} | The data relative to this Live API event | Object |
| timestamp | 1421656451382 | The numeric value corresponding to milliseconds since Unix epoch | Number |
Possible Types
| Type |
|---|
| re.notifica.import.Imported |
| re.notifica.import.Verified |
| re.notifica.import.Failed |
Payload
| Key | Description |
|---|
| id | The Id of the import job executed |
Expected Response
Your server should reply in a certain manner whenever you handle the verification or the payload of events. This is crucial for this API to be able to either activate the service, discard handled events or retry events whenever your server cannot handle them.
Verification
Before you can start receiving any events, you must implement a verification endpoint. This is the first step to activate the service. Only after a successful verification this LIVE API will start sending all the events that occur in your application. For that make sure you respond with a 200 status code whenever you attempt to validate the service. The response also should include a digest of the public key as the response payload body.
Payload Handling
Once the service is active you will start receiving all events that happen in your application. To signal the LIVE API that you've handle the event and it should be discarded, reply with a 200s code range. In case your server is busy, not accessible or simply you when cannot handle the event, reply with a 400s or 500s code range and our API will keep retrying any event until it gets a successful response from your server.
