Events API

The Events API allows you to track server-side events that relate to an end user's in-app activity.

Introduction

Localytics maintains platform-specific SDKs to help you measure and improve app engagement with ease, reliability, and precision. Our SDKs enable rich multi-channel messaging and make it simple for you to track user behavior by decreasing implementation complexity, providing bandwidth management/retry logic, and performing sophisticated de-duplication capabilities.

But in some situations, in-app activity alone does not provide a full picture of your users’ engagement with your app.

For example: for eCommerce apps, the most important conversion events are typically purchases. An end user initiates a purchase in-app, but the purchase usually “finishes” on a merchant’s backend server infrastructure — after the merchant completes payment processing, inventory management, and shipping verification. The most reliable way to track purchases would be to use the Events API to record a serverside “purchase complete” event when these processes are successfully completed.

Similar serverside conversions happen in other types of apps:

  • “subscription complete” for media apps
  • “delivery complete” for demand-economy apps
  • “in-app purchase complete” for commerce apps/games
The Localytics Events API allows you to track these types of server-side events alongside event data captured from apps instrumented with the Localytics SDK.

Localytics processes web services calls to the Events API in near real-time (at equivalent speed to events tagged with a Localytics SDK). Events will be usable in Localytics Analytics and Marketing campaign performance reporting, and available for audience targeting.

Getting Started

The Events API accepts HTTP POST transactions authenticated with an API key/secret. At a high level, a transaction includes the following information:

  • Authentication - API key and secret that allows Localytics to authenticate your transaction.
  • One or more event requests.

Each event request within a transaction includes the following types of information:

  • App identification - Your app’s Localytics App ID.
  • User Data - Customer ID for an end user of your app.
  • Event Data - Data such as the event name, event time, event attributes (optional), and LTV change (optional).
  • Request Identifier - UUID that identifies each event request; used to ensure uniqueness/guarantee that each event request gets processed exactly once.

The Events API supports batching multiple event requests in JSON line format within the POST body of a single transaction. The POST body can be plaintext or compressed using gzip, but must be smaller than 256KB (usually about 250 events plaintext / 10,000 events compressed).

We recommend batching event requests within a single transaction to make it easier for your servers to accommodate changes in your request load.

Implementation Details

To employ the Localytics Events API, your app must already be identifying your users by setting customer ID ( iOS / Android ). Within the scope of the app you specify, Localytics will apply event requests to the last device that a customer was active on. This means that you can only send Events API requests for people who have used your app at least once.

When you instrument your app with a Localytics SDK, the Localytics platform helps you to understand your app engagement by allowing you to set Custom Dimensions and by tracking many important Dimensions automatically (e.g. Country, Language, App Version). When you send an event request, you will probably not have access to all of the Dimensions tracked by the Localytics SDK. The Events API makes it easy for you to track engagement along these Dimensions by tagging event requests with the last Dimensions recorded for the last device that a customer was active on. This means that if you employ the Events API to record a “purchase complete” event for a given end user, Localytics will assume that the user accomplished this event with his or her most recent values for Country, Language, Device, App Version, etc. This means that events recorded using the Events API can be used for targeting and to drive Analytics charts — akin to any in-app event.

At the API level, the Localytics Events API validates that your event request is correctly formatted, but does not perform extensive content-level validation. If you send a correctly-formatted event request for a person who has not used your app, the Events API will accept the request but will not create an event or a new user.

The same best practices that apply to events tagged using Localytics SDKs also apply to events created using the Events API. So you should deliberately structure your event names (not create hundreds or thousands of differently-named events), use consistent attributes for the same event, etc. Please be aware that events created using the Events API count towards your org’s monthly Datapoint allotment for billing purposes.

Events API Transactions

API Endpoint

The base URL for all transactions is:

https://analytics.localytics.com/events/[api_version]/uploads
During the beta for this feature, [api_version] will be ‘v0’

The Content-Type HTTP header for each transaction should specify the format of the transaction's POST body (either application/json for plaintext or application/x-gzip for gzipped).

Authentication

The Localytics Events API uses Basic Access Authentication. You can use your org’s API Key/Secret to authenticate Events API transactions. These are the same credentials you use to authenticate transactions with the Localytics Profile API or Push API.

You can find your org’s API Key/Secret by navigating to the “API Keys” section of the “Account” page in the Localytics Dashboard.

Rate Limits

The Localytics Events API enforces the following rate limits per API Key:

  • 150 transactions per second.

Event Request Parameters

The Localytics Events API accepts event requests in JSON Line format according to a published schema. This means that each event request must be formatted as a single line. The individual event request within a transaction should be separated by a newline.

Parameter Required? Description
schema_url Required (String) URL indicating the Localytics Events API JSON Schema version for the event request.

During the beta period, must be: https://localytics-files.s3.amazonaws.com/schemas/eventsApi/v0.json
app_uuid Required (String) Your Localytics App ID.

Example: 91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f
customer_id Required (String) Localytics Customer ID that identifies the end user who completed the event.

Example: joanna@localytics.com
event_name Required (String) The name of the event; limited to 128 characters.

Example: Purchase_Completed
event_time Required (Integer) The time that the event occurred, in milliseconds since epoch (GMT). For example, a value of “1412090428444” would indicate an event time of “30 Sep 2014 15:20:28.444 GMT”

Event timestamps must be more recent than 72 hours in the past and must not exceed 2 days in the future.

Example: 1412090428444
uuid Required (UUID) UUID that uniquely identifies this event request; required to mitigate networking problems and ensure that each event is processed exactly once. The UUID should be randomly generated.

UUIDs must be 32-75 characters in length and contain only hex characters and dashes (0-9, a-f, A-F, -).

Example: fabfec96-7aff-40cc-a37d-972c4b4265de
attributes Optional (Object) JSON object containing key/value pairs representing user-defined event attribute names and their values.

An event can have up to 50 event attributes. Although Localytics supports numeric or string event attributes, attribute values of both types should be formatted as strings. Attribute names and values can be up to 128 characters in length.

Example: { "My String Attribute": "Value", "My Numeric Attribute": "235" }
ltv_change Optional (Integer) Incremental change in user’s lifetime value associated with this event. Must be an integer value ($2.99 = 299).

Example: 299

Examples

Transaction with a Single Event Request

    curl \
    -i -H "Accept application/json" \
    -H "Content-Type: application/json" \
    -u API_KEY:API_SECRET \
    -X POST \
    -d '{ "schema_url": "https://localytics-files.s3.amazonaws.com/schemas/eventsApi/v0.json", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "joanna@localytics.com", "event_name": "Purchase_Completed", "event_time": 1412090428444, "uuid": "fabfec96-7aff-40cc-a37d-972c4b4265de", "attributes": { "My String Attribute": "Value", "My Numeric Attribute": "235" }, "ltv_change": 299 }' \
    https://analytics.localytics.com/events/v0/uploads
    

Transaction with Multiple Event Requests

    curl \
    -i -H "Accept application/json" \
    -H "Content-Type: application/json" \
    -u API_KEY:API_SECRET \
    -X POST \
    -d '{ "schema_url": "https://localytics-files.s3.amazonaws.com/schemas/eventsApi/v0.json", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "joanna@localytics.com", "event_name": "Purchase_Completed", "event_time": 1412090428444, "uuid": "fabfec96-7aff-40cc-a37d-972c4b4265de", "attributes": { "My String Attribute": "Value", "My Numeric Attribute": "235" }, "ltv_change": 299 }
    { "schema_url": "https://localytics-files.s3.amazonaws.com/schemas/eventsApi/v0.json", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "jen@localytics.com", "event_name": "Some_Event", "event_time": 1412090428488, "uuid": "8dbbbbe7-fe80-4ad9-ba5d-67679a0f20e5" }' \
    https://analytics.localytics.com/events/v0/uploads
    

Response

The Localytics Events API will return a 202 response code if your transaction is correctly formatted. The Events API does not validate the correctness of the event requests within a transaction — a 202 response code only indicates that the transaction was accepted.

More precisely, the Events API will verify that:

  • Authorization succeeded
  • Request headers were properly-formatted
  • Content-Type was valid
  • If the POST body was gzipped, the gzip is valid
  • The POST body was ≤ 256 KB
  • The transaction was successfully accepted for processing
Individual event requests within a transaction may still fail during downstream processing if event request parameters are invalid, if a customer ID does not correspond to an active app user, etc. The “Troubleshooting” section outlines best practices for verifying that your event requests are properly constructed.

HTTP Response Codes

The Localytics Events API returns the following HTTP response codes:

Code Description
202 The transaction was correctly formatted.
400 A required parameter is missing or malformed.
401 The supplied API key/secret parameters were not valid.
413 The POST body was larger than 256 KB.
415
  • The Content-Type was not valid (only ‘application/json’ or ‘application/x-gzip’ are allowed).
  • The Content-Type was ‘application/x-gzip’ but the POST body did not contain a valid gzipped payload.
429 The transaction exceeded the API’s rate limit.

Testing

Localytics maintains versioned JSON schemas for Events API requests. The most current schema is v0: https://localytics-files.s3.amazonaws.com/schemas/eventsApi/v0.json

To enable quick testing without actually creating events in Localytics, you can validate that your event requests are valid JSON with a linter such as: http://jsonlint.com/

And you can validate that your event requests match a Localytics JSON Schema by using using a JSON schema validator such as: http://jsonschemalint.com/draft4/

Like events tagged using a Localytics SDK, events that you create using the Events API cannot be deleted or removed. We strongly suggest that you employ a dev app_uuid (NOT your production app_uuid) when you develop and test services that use the Events API.

Troubleshooting

If the Localytics Events API rejects your transactions:

  • Are you authenticating your requests with your org’s API Key/Secret?

If the Localytics Events API accepts your transactions, but your event requests do not appear in the Localytics Dashboard within 20 minutes:

  • Have you tested that your event requests are valid JSON and conform to the appropriate JSON Schema?
  • Are the event requests in a transaction formatted as JSON lines? Specifically, line breaks in the POST body of a transaction should only separate event requests — there should not be line breaks between the JSON key-values in a single event request.
  • Does your app set customer_id?
  • Are you specifying the customer_id parameter in your event requests in the same format as the Customer ID you set in your app? For example, does your app set Customer ID to a hashed value of your system’s internal identifier?
  • Did the customer_id in your requests have a session in your app?
  • Are you specifying event_time in milliseconds since epoch? By default, the time libraries for some programming languages specify time in seconds since epoch.
  • Are you providing a unique uuid parameter with each event request?

If you’re unable to identify a problem:

    • During the beta period for the Events API, please contact the Localytics Product team to access logs for event requests that were rejected during processing.

  • Version History

    Version Date Change Summary
    0.1 5/10/2016 Initial draft.
    0.2 5/25/2016 Revision for beta participants.
    0.3 7/5/2016 Finalized API endpoint.
    0.4 7/12/2016 Added JSON schema URL.
    0.5 7/26/2016 Clarified JSON lines, revised endpoint versioning. Beta release version.