Menu
Amazon Pinpoint
Developer Guide

Streaming Amazon Pinpoint Events to Kinesis

The Kinesis platform offers services that you can use to load and analyze streaming data on AWS. You can configure Amazon Pinpoint to send events to Amazon Kinesis Firehose or Amazon Kinesis Streams. By streaming your events, you enable more flexible options for analysis and storage. For more information, and for instructions on how to set up event streaming in the Amazon Pinpoint console, see Streaming App and Campaign Events with Amazon Pinpoint in the Amazon Pinpoint User Guide.

Setting up Event Streaming

The following examples demonstrate how to configure Amazon Pinpoint to automatically send the event data from an app to an Kinesis stream or Kinesis Firehose delivery stream.

Prerequisites

These examples require the following input:

AWS CLI

The following AWS CLI example uses the put-event-stream command. This command configures Amazon Pinpoint to send app and campaign events to an Kinesis stream:

Copy
aws pinpoint put-event-stream --application-id application-id --write-event-stream DestinationStreamArn=stream-arn,RoleArn=role-arn

AWS SDK for Java

The following Java example configures Amazon Pinpoint to send app and campaign events to an Kinesis stream:

Copy
public PutEventStreamResult createEventStream(AmazonPinpoint pinClient, String appId, String streamArn, String roleArn) { WriteEventStream stream = new WriteEventStream() .withDestinationStreamArn(streamArn) .withRoleArn(roleArn); PutEventStreamRequest request = new PutEventStreamRequest() .withApplicationId(appId) .withWriteEventStream(stream); return pinClient.putEventStream(request); }

This example constructs a WriteEventStream object that stores the ARNs of the Kinesis stream and the IAM role. The WriteEventStream object is passed to a PutEventStreamRequest object to configure Amazon Pinpoint to stream events for a specific app. The PutEventStreamRequest object is passed to the putEventStream method of the Amazon Pinpoint client.

You can assign an Kinesis stream to multiple apps. Amazon Pinpoint will send event data from each app to the stream, enabling you to analyze the data as a collection. The following example method accepts a list of app IDs, and it uses the previous example method, createEventStream, to assign a stream to each app:

Copy
public List<PutEventStreamResult> createEventStreamFromAppList( AmazonPinpoint pinClient, List<String> appIDs, String streamArn, String roleArn) { return appIDs.stream() .map(appId -> createEventStream(pinClient, appId, streamArn, roleArn)) .collect(Collectors.toList()); }

With Amazon Pinpoint, you can assign one stream to multiple apps, but you cannot assign multiple streams to one app.

Disabling Event Streaming

If you assigned an Kinesis stream to an app, you can disable event streaming for that app. Amazon Pinpoint stops streaming the events, but you can view analytics based on the events in the Amazon Pinpoint console.

AWS CLI

Use the delete-event-stream command:

Copy
aws pinpoint delete-event-stream --application-id application-id

AWS SDK for Java

Use the deleteEventStream method of the Amazon Pinpoint client:

Copy
pinClient.deleteEventStream(new DeleteEventStreamRequest().withApplicationId(appId));

Event Data

After you set up event streaming, Amazon Pinpoint sends each event reported by your application, and each campaign event created by Amazon Pinpoint, as a JSON data object to your Kinesis stream.

The event type is indicated by the event_type attribute in the event JSON object.

App Events

After you integrate your app with Amazon Pinpoint and you run one or more campaigns, Amazon Pinpoint streams events about user activity and campaign message deliveries.

Example

The JSON object for an appevent contains the data shown in the following example.

Copy
{ "event_type": "_session.stop", "event_timestamp": 1487973802507, "arrival_timestamp": 1487973803515, "event_version": "3.0", "application": { "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "cognito_identity_pool_id": "us-east-1:a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6", "package_name": "main.page", "sdk": { "name": "aws-sdk-mobile-analytics-js", "version": "0.9.1:2.4.8" }, "title": "title", "version_name": "1.0", "version_code": "1" }, "client": { "client_id": "m3n4o5p6-a1b2-c3d4-e5f6-g7h8i9j0k1l2", "cognito_id": "us-east-1:i9j0k1l2-m3n4-o5p6-a1b2-c3d4e5f6g7h8" }, "device": { "locale": { "code": "en_US", "country": "US", "language": "en" }, "make": "generic web browser", "model": "Unknown", "platform": { "name": "android", "version": "10.10" } }, "session": { "session_id": "f549dea9-1090-945d-c3d1-e496780baac5", "start_timestamp": 1487973202531, "stop_timestamp": 1487973802507 }, "attributes": {}, "metrics": {} }

Standard App Event Types

Amazon Pinpoint streams the following standard types for app events:

  • _campaign.send

  • _monetization.purchase

  • _session.start

  • _session.stop

  • _session.pause

  • _session.resume

  • _userauth.sign_in

  • _userauth.sign_up

  • _userauth.auth_fail

Email Events

If the email channel is enabled, Amazon Pinpoint streams events about email deliveries, complaints, opens, and more.

Example

The JSON object for an email event contains the data shown in the following example.

Copy
{ "event_type": "_email.delivered", "event_timestamp": 1487973802507, "arrival_timestamp": 1487973803515, "event_version": "3.0", "application": { "app_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "cognito_identity_pool_id": "us-east-1:a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6", "package_name": "main.page", "sdk": { "name": "aws-sdk-mobile-analytics-js", "version": "0.9.1:2.4.8" }, "title": "title", "version_name": "1.0", "version_code": "1" }, "client": { "client_id": "m3n4o5p6-a1b2-c3d4-e5f6-g7h8i9j0k1l2", "cognito_id": "us-east-1:i9j0k1l2-m3n4-o5p6-a1b2-c3d4e5f6g7h8" }, "device": { "locale": { "code": "en_US", "country": "US", "language": "en" }, "make": "generic web browser", "model": "Unknown", "platform": { "name": "android", "version": "10.10" } }, "session": { "session_id": "f549dea9-1090-945d-c3d1-e496780baac5", "start_timestamp": 1487973202531, "stop_timestamp": 1487973802507 }, "attributes": {}, "metrics": {} }

Standard Email Event Types

Amazon Pinpoint streams the following standard types for the email channel:

  • _email.send

  • _email.delivered

  • _email.rejected

  • _email.hardbounce

  • _email.softbounce

  • _email.complaint

  • _email.open

  • _email.click

  • _email.unsubscribe

SMS Events

If the SMS channel is enabled, Amazon Pinpoint streams events about SMS deliveries.

Example

The JSON object for an SMS event contains the data shown in the following example.

Copy
{ "account_id": "123412341234", "event_type": "_SMS.SUCCESS", "arrival_timestamp": 2345678, "timestamp": 13425345, "timestamp_created": "1495756908285", "application_key": "AppKey-688037015201", "unique_id": "uniqueId-68803701520114087975969", "attributes": { "message_id": "12234sdv", "sender_request_id": "abdfg", "number_of_message_parts": 1, "record_status": "SUCCESS", "message_type": "Transactional", "keyword": "test", "mcc_mnc": "456123", "iso_country_code": "US" }, "metrics": { "price_in_millicents_usd": 0.0 }, "facets": {}, "additional_properties": {} }

Standard SMS Event Types

Amazon Pinpoint streams the following standard types for the SMS channel:

  • _sms.send

  • _sms.success

  • _sms.fail

  • _sms.optout

Event Attributes

The JSON object for an event contains the following attributes.

Event

Attribute Description
event_type The type of event reported by your app.
event_timestamp The time at which the event is reported as Unix time in milliseconds. If your app reports events using the AWS Mobile SDK for Android or the AWS Mobile SDK for iOS, the time stamp is automatically generated.
arrival_timestamp The time at which the event is received by Amazon Pinpoint as Unix time in milliseconds. Does not apply to campaign events.
event_version The version of the event JSON schema.

Check this version in your event-processing application so that you know when to update the application in response to a schema update.

application Your Amazon Pinpoint app. See the Application table.
client The app client installed on the device that reports the event. See the Client table.
device The device that reports the event. See the Device table.
session The app session on the device. Typically a session begins when a user opens your app.
attributes Custom attributes that your app reports to Amazon Pinpoint as part of the event.
metrics Custom metrics that your app reports to Amazon Pinpoint as part of the event.

Application

Attribute Description
app_id The unique ID of the Amazon Pinpoint app that reports the event.
cognito_identity_pool_id The unique ID of the Amazon Cognito identity pool used by your app.
package_name The name of your app package. For example, com.example.my_app.
sdk The SDK used to report the event.
title The title of your app.
version_name The customer-facing app version, such as V2.0.
version_code The internal code that represents your app version.

Client

Attribute Description
client_id The unique ID for the app client installed on the device. This ID is automatically generated by the AWS Mobile SDK for iOS and the AWS Mobile SDK for Android.
cognito_id The unique ID assigned to the app client in the Amazon Cognito identity pool used by your app.

Device

Attribute Description
locale The device locale.
make The device make, such as Apple or Samsung.
model The device model, such as iPhone.
platform The device platform, such as ios or android.

Session

Attribute Description
session_id The unique ID for the app session.
start_timestamp The time at which the session starts as Unix time in milliseconds.
stop_timestamp The time at which the session stops as Unix time in milliseconds.