Name:
interface
Value:
Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Events

You are currently viewing the AWS SDK for Mobile documentation which is a collection of low-level libraries. Use the Amplify libraries for all new app development. Learn more

You can use the AWS Android SDK for Pinpoint to report usage data, or events, to Amazon Pinpoint. You can report events to capture information such as session times, users’ purchasing behavior, sign-in attempts, or any custom event type that you need.

After your application reports events, you can view analytics in the Amazon Pinpoint console. The charts on the Analytics page provide metrics for many aspects of user behavior. For more information, see Chart Reference for Amazon Pinpoint Analytics in the Amazon Pinpoint User Guide.

To analyze and store your event data outside of Amazon Pinpoint, you can configure Amazon Pinpoint to stream the data to Amazon Kinesis. For more information, see Streaming Amazon Pinpoint Events to Kinesis.

By using the PinpointManager in AWS Android SDK for Pinpoint, you can call the Amazon Pinpoint API to report the following types of events:

Session events

Indicate when and how often users open and close your app.

After your application reports session events, use the Analytics page in the Amazon Pinpoint console to view charts for Sessions, Daily active endpoints, 7-day retention rate, and more.

import com.amazonaws.mobileconnectors.pinpoint.analytics.SessionClient;
/**
* Call this method to start and stop a session and submit events recorded
* in the current session.
*/
public void logSession() {
SessionClient sessionClient = pinpointManager.getSessionClient();
sessionClient.startSession();
sessionClient.stopSession();
pinpointManager.getAnalyticsClient().submitEvents();
}

Custom events

Are nonstandard events that you define by assigning a custom event type. You can add custom attributes and metrics to a custom event.

On the Analytics page in the console, the Events tab displays metrics for all custom events that are reported by your app. Use graphs of your custom usage event data in the Amazon Pinpoint console. Visualize how your users’ behavior aligns with a model you design using Amazon Pinpoint Funnel Analytics, or use stream the data for deeper analysis.

Use the following steps to implement Amazon Pinpoint custom analytics for your app.

import com.amazonaws.mobileconnectors.pinpoint.analytics.AnalyticsEvent;
/**
* Call this method to log a custom event to the analytics client.
*/
public void logEvent() {
final AnalyticsEvent event =
pinpointManager.getAnalyticsClient().createEvent("EventName")
.withAttribute("DemoAttribute1", "DemoAttributeValue1")
.withAttribute("DemoAttribute2", "DemoAttributeValue2")
.withMetric("DemoMetric1", Math.random());
pinpointManager.getAnalyticsClient().recordEvent(event);
pinpointManager.getAnalyticsClient().submitEvents();
}

Build, run, and use your app. Then, view your custom events on the Events tab of the Amazon Pinpoint console (choose Analytics>Events). Look for the name of your event in the Events menu.

Monetization events

Report the revenue that’s generated by your application and the number of items that are purchased by users.

On the Analytics page, the Revenue tab displays charts for Revenue, Paying users, Units sold, and more.

Use the following steps to implement Amazon Pinpoint monetization analytics for your app.

import com.amazonaws.mobileconnectors.pinpoint.analytics.monetization.AmazonMonetizationEventBuilder;
/**
* Call this method to log a monetized event to the analytics client.
*/
public void logMonetizationEvent() {
final AnalyticsEvent event =
AmazonMonetizationEventBuilder.create(pinpointManager.getAnalyticsClient())
.withCurrency("USD")
.withItemPrice(10.00)
.withProductId("DEMO_PRODUCT_ID")
.withQuantity(1.0)
.withProductId("DEMO_TRANSACTION_ID").build();
pinpointManager.getAnalyticsClient().recordEvent(event);
pinpointManager.getAnalyticsClient().submitEvents();
}

Authentication events

Indicate how frequently users authenticate with your application.

On the Analytics page, the Users tab displays charts for Sign-ins, Sign-ups, and Authentication failures.

To learn how frequently users authenticate with your app, update your application code so that Amazon Pinpoint receives the following standard event types for authentication:

  • _userauth.sign_in
  • _userauth.sign_up
  • _userauth.auth_fail

You can report authentication events by doing either of the following:

Managing user sign-up and sign-in with Amazon Cognito user pools

Amazon Cognito user pools are user directories that make it easier to add sign-up and sign-in to your app. As users authenticate with your app, Amazon Cognito reports authentication events to Amazon Pinpoint. For more information, see Using Amazon Pinpoint Analytics with Amazon Cognito User Pools in the Amazon Cognito Developer Guide. Also update awsconfiguration.json by adding the pinpoint appid under CognitoUserPool.

"CognitoUserPool": {
"Default": {
"PoolId": "<poolid>",
"AppClientId": "<appclientid>",
"Region": "<region>",
"PinpointAppId": "<pinpointappid>"
}
}

Reporting authentication events by using the Amazon Pinpoint client that’s provided by the AWS Mobile SDK for Android.

If you don’t want to use Amazon Cognito user pools, you can use the Amazon Pinpoint client to record and submit authentication events, as shown in the following examples. In these examples, the event type is set to _userauth.sign_in, but you can substitute any authentication event type.

import com.amazonaws.mobileconnectors.pinpoint.analytics.AnalyticsEvent;
/**
* Call this method to log an authentication event to the analytics client.
*/
public void logAuthenticationEvent() {
final AnalyticsEvent event =
pinpointManager.getAnalyticsClient().createEvent("_userauth.sign_in");
pinpointManager.getAnalyticsClient().recordEvent(event);
pinpointManager.getAnalyticsClient().submitEvents();
}

Custom App events

Instrument your code to capture app usage event information, including attributes you define. Use graphs of your custom usage event data in the Amazon Pinpoint console. Visualize how your users' behavior aligns with a model you design using Amazon Pinpoint Funnel Analytics, or use stream the data for deeper analysis.

Use the following steps to implement Amazon Pinpoint custom analytics for your app.

import com.amazonaws.mobileconnectors.pinpoint.analytics.AnalyticsEvent;
/**
* Call this method to log a custom event to the analytics client.
*/
public void logEvent() {
final AnalyticsEvent event =
pinpointManager.getAnalyticsClient().createEvent("EventName")
.withAttribute("DemoAttribute1", "DemoAttributeValue1")
.withAttribute("DemoAttribute2", "DemoAttributeValue2")
.withMetric("DemoMetric1", Math.random());
pinpointManager.getAnalyticsClient().recordEvent(event);
}

Build, run, and use your app. Then, view your custom events on the Events tab of the Amazon Pinpoint console (choose Analytics>Events). Look for the name of your event in the Events menu.

Enable Revenue Analytics

Amazon Pinpoint supports the collection of monetization event data. Use the following steps to place and design analytics related to purchases through your app.

import com.amazonaws.mobileconnectors.pinpoint.analytics.monetization.AmazonMonetizationEventBuilder;
/**
* Call this method to log a monetized event to the analytics client.
*/
public void logMonetizationEvent() {
final AnalyticsEvent event =
AmazonMonetizationEventBuilder.create(pinpointManager.getAnalyticsClient())
.withCurrency("USD")
.withItemPrice(10.00)
.withProductId("DEMO_PRODUCT_ID")
.withQuantity(1.0)
.withProductId("DEMO_TRANSACTION_ID").build();
pinpointManager.getAnalyticsClient().recordEvent(event);
}

Event Ingestion Limits

The limits applicable to the ingestion of events using the AWS Android SDK for Pinpoint and the Amazon Pinpoint Events API can be found here.

Managing Sessions in Your Application

As users engage with your app, it reports information about app sessions to Amazon Pinpoint, such as session start times, session end times, and events that occur during sessions. To report this information from an Android application, your app must include methods that handle events as your app enters the foreground and the background on the user's Android device.

Example Lifecycle Manager

The following example class, AbstractApplicationLifeCycleHelper, implements the Application.ActivityLifecycleCallbacks interface to track when the application enters the foreground or background, among other states. Add this class to your app, or use it as an example for how to update your code:

package com.amazonaws.mobile.util;
import android.app.Activity;
import android.app.Application;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.content.IntentFilter;
import android.os.Bundle;
import android.util.Log;
import java.util.WeakHashMap;
/**
* Aids in determining when your application has entered or left the foreground.
* The constructor registers to receive Activity lifecycle events and also registers a
* broadcast receiver to handle the screen being turned off. Abstract methods are
* provided to handle when the application enters the background or foreground.
* Any activity lifecycle callbacks can easily be overridden if additional handling
* is needed. Just be sure to call through to the super method so that this class
* will still behave as intended.
**/
public abstract class AbstractApplicationLifeCycleHelper implements Application.ActivityLifecycleCallbacks {
private static final String LOG_TAG = AbstractApplicationLifeCycleHelper.class.getSimpleName();
private static final String ACTION_SCREEN_OFF = "android.intent.action.SCREEN_OFF";
private boolean inForeground = false;
/** Tracks the lifecycle of activities that have not stopped (including those restarted). */
private WeakHashMap<Activity, String> activityLifecycleStateMap = new WeakHashMap<>();
/**
* Constructor. Registers to receive activity lifecycle events.
* @param application The Android Application class.
*/
public AbstractApplicationLifeCycleHelper(final Application application) {
application.registerActivityLifecycleCallbacks(this);
final ScreenOffReceiver screenOffReceiver = new ScreenOffReceiver();
application.registerReceiver(screenOffReceiver, new IntentFilter(ACTION_SCREEN_OFF));
}
@Override
public void onActivityCreated(final Activity activity, final Bundle bundle) {
Log.d(LOG_TAG, "onActivityCreated " + activity.getLocalClassName());
handleOnCreateOrOnStartToHandleApplicationEnteredForeground();
activityLifecycleStateMap.put(activity, "created");
}
@Override
public void onActivityStarted(final Activity activity) {
Log.d(LOG_TAG, "onActivityStarted " + activity.getLocalClassName());
handleOnCreateOrOnStartToHandleApplicationEnteredForeground();
activityLifecycleStateMap.put(activity, "started");
}
@Override
public void onActivityResumed(final Activity activity) {
Log.d(LOG_TAG, "onActivityResumed " + activity.getLocalClassName());
activityLifecycleStateMap.put(activity, "resumed");
}
@Override
public void onActivityPaused(final Activity activity) {
Log.d(LOG_TAG, "onActivityPaused " + activity.getLocalClassName());
activityLifecycleStateMap.put(activity, "paused");
}
@Override
public void onActivityStopped(final Activity activity) {
Log.d(LOG_TAG, "onActivityStopped " + activity.getLocalClassName());
// When the activity is stopped, you remove it from the lifecycle state map since you
// no longer consider it keeping a session alive.
activityLifecycleStateMap.remove(activity);
}
@Override
public void onActivitySaveInstanceState(final Activity activity, final Bundle outState) {
Log.d(LOG_TAG, "onActivitySaveInstanceState " + activity.getLocalClassName());
}
@Override
public void onActivityDestroyed(final Activity activity) {
Log.d(LOG_TAG, "onActivityDestroyed " + activity.getLocalClassName());
// Activity should not be in the activityLifecycleStateMap any longer.
if (activityLifecycleStateMap.containsKey(activity)) {
Log.wtf(LOG_TAG, "Destroyed activity present in activityLifecycleMap!?");
activityLifecycleStateMap.remove(activity);
}
}
/**
* Call this method when your Application trims memory.
* @param level the level passed through from Application.onTrimMemory().
*/
public void handleOnTrimMemory(final int level) {
Log.d(LOG_TAG, "onTrimMemory " + level);
// If no activities are running and the app has gone into the background.
if (level >= Application.TRIM_MEMORY_UI_HIDDEN) {
checkForApplicationEnteredBackground();
}
}
class ScreenOffReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
checkForApplicationEnteredBackground();
}
}
/**
* Called back when your application enters the Foreground.
*/
protected abstract void applicationEnteredForeground();
/**
* Called back when your application enters the Background.
*/
protected abstract void applicationEnteredBackground();
/**
* Called from onActivityCreated and onActivityStarted to handle when the application enters
* the foreground.
*/
private void handleOnCreateOrOnStartToHandleApplicationEnteredForeground() {
// if nothing is in the activity lifecycle map indicating that you are likely in the background, and the flag
// indicates you are indeed in the background.
if (activityLifecycleStateMap.size() == 0 && !inForeground) {
inForeground = true;
// Since this is called when an activity has started, you now know the app has entered the foreground.
applicationEnteredForeground();
}
}
private void checkForApplicationEnteredBackground() {
ThreadUtils.runOnUiThread(new Runnable() {
@Override
public void run() {
// If the App is in the foreground and there are no longer any activities that have not been stopped.
if ((activityLifecycleStateMap.size() == 0) && inForeground) {
inForeground = false;
applicationEnteredBackground();
}
}
});
}
}

Reporting Session Events

After you include the AbstractApplicationLifeCycleHelper class, implement the two abstract methods, applicationEnteredForeground and applicationEnteredBackground, in the Application class. These methods enable your app to report the following information to Amazon Pinpoint:

  1. Session start times (when the app enters the foreground).

  2. Session end times (when the app enters the background).

  3. The events that occur during the app session, such as monetization events. This information is reported when the app enters the background.

The following example shows how to implement applicationEnteredForeground and applicationEnteredBackground. It also shows how to call handleOnTrimMemory from inside the onTrimMemory function of the Application class:

import com.amazonaws.mobileconnectors.pinpoint.PinpointConfiguration;
import com.amazonaws.mobileconnectors.pinpoint.PinpointManager;
public class Application extends MultiDexApplication {
public static PinpointManager pinpointManager;
private AbstractApplicationLifeCycleHelper applicationLifeCycleHelper;
@Override
public void onCreate() {
super.onCreate();
// . . .
// The Helper registers itself to receive application lifecycle events when it is constructed.
// A reference is kept here in order to pass through the onTrimMemory() call from
// the Application class to properly track when the application enters the background.
applicationLifeCycleHelper = new AbstractApplicationLifeCycleHelper(this) {
@Override
protected void applicationEnteredForeground() {
Application.pinpointManager.getSessionClient().startSession();
// handle any events that should occur when your app has come to the foreground...
}
@Override
protected void applicationEnteredBackground() {
Log.d(LOG_TAG, "Detected application has entered the background.");
Application.pinpointManager.getSessionClient().stopSession();
Application.pinpointManager.getAnalyticsClient().submitEvents();
// handle any events that should occur when your app has gone into the background...
}
};
}
private void updateGCMToken() {
try {
final String gcmToken = InstanceID.getInstance(this).getToken(
"YOUR_SENDER_ID",
GoogleCloudMessaging.INSTANCE_ID_SCOPE
);
Application.pinpointManager.getNotificationClient().registerGCMDeviceToken(gcmToken);
} catch (IOException e) {
e.printStackTrace();
}
}
@Override
public void onTrimMemory(final int level) {
Log.d(LOG_TAG, "onTrimMemory " + level);
applicationLifeCycleHelper.handleOnTrimMemory(level);
super.onTrimMemory(level);
}
}

You've updated your Android app to report session information. Now, when users open and close your app, you can see session metrics in the Amazon Pinpoint console, including those shown by the Sessions and Session heat map charts.