Events API

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 customers' engagement. As the customer journey becomes more and more complex, marketers need to be able to execute in mobile channels regardless of where the customer touchpoint is.

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 “purchase complete” event when these processes are successfully completed.

Similar API-triggered events happen in other types of apps:

• Smart-speaker skill invocation ("Alexa, ask the Sports_App when's the next game")
• Purchase registered via a brick and mortar store Point of Sale
• Account update performed via a request to a call center operator

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

Events API requests must be associated with a valid App ID. Localytics provides a special type of app platform called API. This is specifically for integrations with clients—such as point of sale systems or smart speakers via API calls.

If you're using an API platform app, you'll be able to set the Customer ID via the Events API. If, however, you're using a non API app (for example, iOS or Android platform) the Customer ID must already be set within Localytics, and you'll want to use the Events API to reference that Customer ID (iOS/Android)

It is recommended that the App ID provided with the request is that of an API platform. Events API will accept requests with an App ID corresponding to a device app (for example, iOS or Android platform) however for such requests Localytics will apply events to the last device that a customer was active on. This means that unless you use API platform App ID, 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). Events API requests typically do not have access to most dimensions or sessions data. For the App IDs associated with device platforms the Events API makes it easy for you to track engagement along various 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 with a non-API App ID 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

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.

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/v1.json", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "isa@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/v1/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/v1.json", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "isa@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/v1.json", "app_uuid": "91e6f7bf1c6004b029c3082-602f5774-ae2b-11e2-0c2c-004a77f8b47f", "customer_id": "jen@example.com", "event_name": "Some_Event", "event_time": 1412090428488, "uuid": "8dbbbbe7-fe80-4ad9-ba5d-67679a0f20e5" }' \
    https://analytics.localytics.com/events/v1/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

HTTP Response Codes

The Localytics Events API returns the following HTTP response codes:

Testing

Localytics maintains versioned JSON schemas for Events API requests. The most current schema is v1: https://localytics-files.s3.amazonaws.com/schemas/eventsApi/v1.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: https://jsonlint.com/

And you can validate that your event requests match a Localytics JSON Schema by using using a JSON schema validator such as: https://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?
• Are you using API platform as your App ID? If not 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?

Version History