Publish Usage Events

The Productiv platform is powered by recording real-time usage events for a customer per an application. These usage events represent different activity or actions that a given user performs on an app. Events like starting a video call on a conferencing app, sending a message on a chat app, sending an email, uploading a file, downloading a file are all examples of different usage events that can be tracked and shown in product. Every Event pushed to Productiv will be uniquely identified by the timestamp, email, and eventName combination.

This API can be used to push all usage events for an app to Productiv.

Prerequisites

  • Before this API can be queried you should have already setup the application for which you will be publishing usage events. Once thats done you should have a unique appId that can be used to query these APIs. Visit the Setup an Application section to see how to do so.

  • In order to query this API, you would also need to send an access_token as part of the Authorization header. To see the steps for generating an access token checkout Authorization.

Publish Usage Events Endpoint

POST https://api.productiv.com/services/push/v1/customer/apps/{appId}/events

Include the following headers and path parameters along with your requests:

Headers

Parameter Value
content-type application/json
Authorization Bearer access_token

Path Params

Parameter Description
appId appId represents the App for which the usage events are being pushed. (See Setup an Application)

Request Body Schema

{
    "events": [ {
       "timestamp": Number,
       "email": String,
       "eventName": String
    }]
}

Usage Event Object

Every usage event should have the following properties in the object:

Property Datatype Description Optional
timestamp Number Unix timestamp in milliseconds of the event. No
email String Email of the user associated to the event. No
eventName String Name of the event provided in mapping during application definition. No
targetApp String Application being logged into. Required if Event Type Category is "Login" (See App Usage Events)

Example Usage Event Object Schema

{
    "timestamp": 1566340678676,
    "email": "testuser@random.com",
    "eventName": "opened_file",
}

Response

If the request is successful, a JSON response will be returned. This JSON object will contain the following parameters:

Parameter Description
success Will be set to true in case of a successful response.

Example Response Schema

{
    "success": true,
}

Response Errors

Error Code Error Message Description
400 Bad Request Returned if any invalid/unexpected query parameter/value is present in the request.
401 Unauthorized Returned if access_token used in request is invalid or expired.
403 Forbidden Returned if access_token does not have the required scope to use this API.
404 Not Found Returned if customer or application specified does not exist.
422 Unprocessable Entity Returned if the request payload is invalid
429 Too Many Requests Returned if rate limit has been exceeded

Example Error Response Schema

{
    "code": "401",
    "message": "Invalid access_token",
    "success": false,
}

SLA

  • You must only send a batch of usage events not more than 1000 at a time.
  • Only events pushed to Productiv within 12 hours of their occurrence are guaranteed to be aggregated and shown on the product page.