RudderStack API specification

Detailed technical description of the APIs supported by RudderStack

Introduction

This RudderStack API specification gives you an idea on how to plan your event data, as well as the various options available for tracking your events. We have an unified event semantic for different destination platforms.

RudderStack Client SDKs support the following API calls:

  1. Identify : Captures the details about the visiting user

  2. Track: Captures information related to the actions performed by the user

  3. Page: Contains information such as the URL / web page visited by the user

  4. Screen: Captures details related to the screen being viewed by the user

  5. Reset: Resets the previously identified user.

These APIs send a set of common information about the user, that helps you get a better context of the user and the associated activities.

Using the RudderStack API

You can choose any of our SDKs (JavaScript, Android or iOS) to use the RudderStack APIs. This section explains in details how to initialize the SDK and gives an overview of the different API calls supported by RudderStack.

Initializing the SDK

The RudderStack SDK needs to be initialized before any API calls are made. Please refer to the code below to initialize the SDK:

RudderClient rudderClient = RudderClient.getInstance(this,
<RUDDER_WRITE_KEY>,
new RudderConfig.Builder().withFactory(BrazeIntegrationFactory.FACTORY));

Identify

The Identify call is used to attach an anonymous user to a known user. Ideally, you should use this call to track the user information when the user is logging in or registering to your platform. You should also update this identification every time the user profile is updated. Furthermore, you can reset the collected user information when the user performs a Logout operation.

The following sample code illustrates identifying an user named Foo Bar with his traits.

RudderTraits traits = new RudderTraits();
traits.putAge("21");
traits.putEmail("test@test.com");
traits.putId("hashed_user_id");
traits.putLastName("Bar");
traits.putFirstName("Foo");
rudderClient.identify(traits);

Click here to know more about the underlying event structure.

Track

The Track call is used to record the user actions. You can use the properties field to describe these actions. RudderStack considers each action as an event and each event has a name associated with it, to define the event.

The track call is illustrated below with an example of the Product Reviewed event of a user, who has submitted a review for some product on an eCommerce website or app.

RudderProperty rudderProperty = new RudderProperty();
rudderProperty.putValue("review_id", "review_id_1");
rudderProperty.putValue("product_id", "product_id_1");
rudderProperty.putValue("rating", 2.0);
rudderProperty.putValue("review_body", "Sample Review Body");
rudderClient.track("Product Reviewed",rudderProperty);

Click here to know more about the underlying event structure.

Page

The Page API uses the RudderStack JavaScript SDK to record a user's page visits on your website. Along with the page call, you can specify some other relevant information like ad_capmaign , utm_source etc.

A sample page view is tracked as shown, along with the properties of the page:

rudderanalytics.page("Dashboard", {
"title" : "Sample Title",
"url" : "https://sample.com/dashboard"
});

Click here to know the underlying payload for this event.

Screen

The Screen API is the mobile app equivalent of the Page API. It records an event when an user views a particular screen on the mobile device.

A sample Screen call with its properties for a dashboard view is as shown below.

RudderProperty rudderProperty = new RudderProperty();
rudderProperty.putValue("variation", "blue signup button");
rudderProperty.putValue("feed", "private");
rudderClient.screen("Dashboard",rudderProperty);

Click here to know the underlying payload for this event.

Reset

The Reset call erases any previously existing user specific traits and data on the client SDK, so that further track calls can be registered for a new/different user.

The reset call is as shown below:

rudderClient.reset();

How the RudderStack API calls work

  1. The RudderStack API calls send the event data to the RudderStack Server.

  2. The server then transforms this data into formats specific to various destination platforms.

  3. The transformed data is then forwarded to the desired destinations such as Google Analytics, Amplitude, MixPanel, and more.

Event Data Format

The event data sent to the RudderStack Server has a JSON structure, which has common fields and an API-specific payload. Both of these formats are described in the subsequent sections.

Common Fields

The common fields define the core structure of the event data. These fields also describe the user identity, as well as other vital information about your app or website.

{
"anonymousId": "7e32188a4dab669f",
"channel": "mobile",
"context": {
"app": {
"build": "1",
"name": "RudderAndroidClient",
"namespace": "com.rudderstack.demo.android",
"version": "1.0"
},
"device": {
"id": "7e32188a4dab669f",
"manufacturer": "Google",
"model": "Android SDK built for x86",
"name": "generic_x86",
"type": "android"
},
"library": {
"name": "com.rudderstack.android.sdk.core",
"version": "0.1.4"
},
"locale": "en-US",
"network": {
"carrier": "Android",
"bluetooth": false,
"cellular": true,
"wifi": true
},
"os": { "name": "Android", "version": "9" },
"screen": { "density": 420, "height": 1794, "width": 1080 },
"timezone": "Asia/Kolkata",
"traits": { "anonymousId": "7e32188a4dab669f" },
"userAgent": "Dalvik/2.1.0 (Linux; U; Android 9; Android SDK built for x86 Build/PSR1.180720.075)"
},
"event": "Product Reviewed",
"integrations": { "All": true },
"messageId": "1578564113557-af022c68-429e-4af4-b99b-2b9174056383",
"properties": {
"review_id": "review_id_1",
"product_id": "product_id_1",
"rating": 2.0,
"review_body": "Sample Review Body"
},
"originalTimestamp": "2020-01-09T10:01:53.558Z",
"type": "track",
"sentAt": "2020-01-09T10:02:03.257Z"
}

A detailed description of the common fields is documented in the table below:

Name

Data Type

Required

Description

anonymousId

String

YES

An unique identification for the user. We keep it the same as the deviceId

channel

String

YES

Identifies the source of the event. Permitted values are mobile, web, server

context

Object

YES

This object contains all the additional information you might need for the user. The SDKs populate this information automatically.

event

String

NO

The user action that you want to record is captured in this string.

integrations

Object

NO

You can specify the destinations here to control the flow the events

messageId

String

NO

Signifies a unique identification for the event

properties

Object

NO

Used to pass all the required information to the destination along with the event

originalTimestamp

Timestamp

YES

Records the actual time when the event occurred

type

String

YES

Captures the type of the API. Values can be either one of the track,screen,identify,page events

sentAt

Timestamp

YES

Captures the time when the event was sent to the RudderStack Server from the client

Contextual Fields

Name

Data Type

Description

app

Object

Gives detailed information of your application such as build, name, namespace and version

device

Object

Information about the device from which you are capturing the event. It contains deviceId, manufacturer, model, name and type

library

Object

Details about the Rudder SDK you are using. name and version

locale

String

Captures the language of the device

network

Object

Contains information about the reachability of the device. Also, it gives you the status of bluetooth, wifi, cellular network and carrier name

os

Object

Details of the operating system of the device you are tracking

screen

Object

It gives you the dimensions, i.e. height, width and the density of the screen of the device

timezone

String

Captures the time zone of the user you are tracking

traits

Object

Contains detailed information of the user. We fill in the anonymousId for you. You can add more details here using identify call from the SDK

userAgent

String

User agent of the device that you are tracking

Sample payload structures

This section demonstrates some sample payloads for the various RudderStack API calls:

Identifypayload

A sample payload for the identify event after removing the common fields mentioned in the Common Fields section:

{
"traits": {
"id": "hashed_user_id",
"email": "sample@example.com",
"userId": "test_user_id",
"lastname": "Bar",
"firstname": "Foo"
},
"userId": "hashed_user_id"
}

Track payload

A sample payload for Product Reviewed event after removing the common fields is as shown:

{
"properties": {
"review_id": "review_id_1",
"product_id": "product_id_1",
"rating": 2.0,
"review_body": "Sample Review Body"
},
"event": "Product Reviewed"
}

Page payload

The following code snippets demonstrates a sample payload for the page call after removing the common fields:

{
"properties": {
"title": "Sample Title",
"url": "https://sample.com/dashboard"
},
"event": "Dashboard"
}

Screen payload

A sample payload for screencall after removing the common fields:

{
"properties": {
"feed" : "private"
},
"event": "Home"
}

Contact Us

If you want to know more about the RudderStack API specs, feel free to contact us. You can also request a demo to see RudderStack in action.