AWS Mobile Hub Developer Guide
Developer Guide

Add Analytics to your Mobile App with Amazon Pinpoint

The following reference content only applies to existing apps that were built using the AWS Mobile SDKs for iOS and Android. If you’re building a new mobile or web app, or you're adding cloud capabilities to an existing app, visit the Amplify Framework website instead. Documentation for the AWS Mobile SDKs for iOS and Android is now part of the Amplify Framework.

Overview

Gather the data that helps improve your app's usability, monetization, and engagement with your users. Mobile Hub deploys your analytics backend when you enable the Messaging and Analytics feature, which uses the Amazon Pinpoint service.

Set up your Backend

  1. Complete the Get Started steps before your proceed.

  2. When you create a project, we enable analytics by default in your backend. You should see a green check mark present on the Analytics tile in your backend, indicating that the feature is enabled. If the check mark is absent, choose Analytics, and then choose Enable.

Connect to your Backend

Use the following steps to add analytics to your mobile app and monitor the results through Amazon Pinpoint.

Add Analytics

Android - JavaAndroid - KotliniOS - Swift
Android - Java
  1. Set up AWS Mobile SDK components as follows.

    1. Include the following libraries in your app/build.gradle dependencies list.

      dependencies{ implementation 'com.amazonaws:aws-android-sdk-pinpoint:2.7.+' implementation ('com.amazonaws:aws-android-sdk-mobile-client:2.7.+@aar') { transitive = true } // other dependencies . . . }
      • aws-android-sdk-pinpoint library enables sending analytics to Amazon Pinpoint.

      • aws-android-sdk-mobile-client library gives access to the AWS credentials provider and configurations.

    2. Add required permissions to your app manifest.

      The AWS Mobile SDK required the INTERNET and ACCESS_NETWORK_STATE permissions. These are defined in the AndroidManifest.xml file.

      <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  2. Add calls to capture session starts and stops.

    Three typical places to instrument your app session start and stop are:

    • Start a session in the Application.onCreate() method.

    • Start a session in the onCreate() method of the app's first activity.

    • Start and/or stop a session in the ActivityLifecycleCallbacks class.

    The following example shows starting a session in the OnCreate event of MainActivity.

    import android.support.v7.app.AppCompatActivity; import android.os.Bundle; import com.amazonaws.mobileconnectors.pinpoint.PinpointManager; import com.amazonaws.mobileconnectors.pinpoint.PinpointConfiguration; import com.amazonaws.mobile.client.AWSMobileClient; public class MainActivity extends AppCompatActivity { public static PinpointManager pinpointManager; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main); // Initialize the AWS Mobile Client AWSMobileClient.getInstance().initialize(this).execute(); PinpointConfiguration config = new PinpointConfiguration( MainActivity.this, AWSMobileClient.getInstance().getCredentialsProvider(), AWSMobileClient.getInstance().getConfiguration() ); pinpointManager = new PinpointManager(config); pinpointManager.getSessionClient().startSession(); pinpointManager.getAnalyticsClient().submitEvents(); } }

    To stop the session, use stopSession() and submitEvents() at the last point in the session you want to capture.

    // . . . pinpointManager.getSessionClient().stopSession(); pinpointManager.getAnalyticsClient().submitEvents(); // . . .
Android - Kotlin
  1. Set up AWS Mobile SDK components as follows.

    1. Include the following libraries in your app/build.gradle dependencies list.

      dependencies { implementation 'com.amazonaws:aws-android-sdk-pinpoint:2.7.+' implementation ('com.amazonaws:aws-android-sdk-mobile-client:2.7.+@aar') { transitive = true } // other dependencies . . . }
      • aws-android-sdk-pinpoint library enables sending analytics to Amazon Pinpoint.

      • aws-android-sdk-mobile-client library gives access to the AWS credentials provider and configurations.

    2. Add required permissions to your app manifest.

      The AWS Mobile SDK required the INTERNET and ACCESS_NETWORK_STATE permissions. These are defined in the AndroidManifest.xml file.

      <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  2. Add calls to capture session starts and stops.

    Three typical places to instrument your app session start and stop are:

    • Start a session in the Application.onCreate() method.

    • Start a session in the onCreate() method of the app's first activity.

    • Start and/or stop a session in the ActivityLifecycleCallbacks class.

    The following example shows starting a session in the OnCreate event of MainActivity.

    import android.support.v7.app.AppCompatActivity; import android.os.Bundle; import com.amazonaws.mobileconnectors.pinpoint.PinpointManager; import com.amazonaws.mobileconnectors.pinpoint.PinpointConfiguration; import com.amazonaws.mobile.client.AWSMobileClient; class MainActivity : AppCompatActivity() { companion object { var pinpointManager: PinpointManager? = null } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_main) // Initialize the AWS Mobile client AWSMobileClient.getInstance().initialize(this).execute() with (AWSMobileClient.getInstance()) { val config = PinpointConfiguration(this, credentialsProvider, configuration) pinpointManager = PinpointManager(config) } pinpointManager?.sessionClient?.startSession() pinpointManager?.analyticsClient?.submitEvents() } }

    To stop the session, use stopSession() and submitEvents() at the last point in the session you want to capture.

    // . . . pinpointManager?.sessionClient?.stopSession(); pinpointManager?.analyticsClient?.submitEvents(); // . . .
iOS - Swift
  1. Set up AWS Mobile SDK components as follows.

  2. The Podfile that you configure to install the AWS Mobile SDK must contain:

    platform :ios, '9.0' target :'YourAppName' do use_frameworks! pod 'AWSPinpoint', '~> 2.6.13' # other pods end

    Run pod install --repo-update before you continue.

    If you encounter an error message that begins "[!] Failed to connect to GitHub to update the CocoaPods/Specs . . .", and your internet connectivity is working, you may need to update openssl and Ruby.

  3. Classes that call Amazon Pinpoint APIs must use the following import statements:

    import AWSCore import AWSPinpoint
  4. Insert the following code into the application(_:didFinishLaunchingWithOptions:) method of your app's AppDelegate.swift.

    class AppDelegate: UIResponder, UIApplicationDelegate { var pinpoint: AWSPinpoint? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool { //. . . // Initialize Pinpoint pinpoint = AWSPinpoint(configuration: AWSPinpointConfiguration.defaultPinpointConfiguration(launchOptions: launchOptions)) //. . . } }

Monitor Analytics

Build and run your app to see usage metrics in Amazon Pinpoint.

  1. To see visualizations of the analytics coming from your app, open your project in the Mobile Hub console.

  2. Choose Analytics on the upper right to open the Amazon Pinpoint console.


               |AMH| console link to your project in the Amazon Pinpoint console.
  1. Choose Analytics from the icons on the left of the console, and view the graphs of your app's usage. It may take up to 15 minutes for metrics to become visible.

Learn more about Amazon Pinpoint.

Enable Custom App Analytics

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.

Android - JavaAndroid - KotliniOS - Swift
Android - Java
import com.amazonaws.mobileconnectors.pinpoint.analytics.AnalyticsEvent; 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(); }
Android - Kotlin
import com.amazonaws.mobileconnectors.pinpoint.analytics.AnalyticsEvent; fun logEvent() { pintpointManager?.analyticsClient?.let { val event = it.createEvent("EventName") .withAttribute("DemoAttribute1", "DemoAttributeValue1") .withAttribute("DemoAttribute2", "DemoAttributeValue2") .withMetric("DemoMetric1", Math.random()); it.recordEvent(event) it.submitEvents() }
iOS - Swift
func logEvent() { let pinpointAnalyticsClient = AWSPinpoint(configuration: AWSPinpointConfiguration.defaultPinpointConfiguration(launchOptions: nil)).analyticsClient let event = pinpointAnalyticsClient.createEvent(withEventType: "EventName") event.addAttribute("DemoAttributeValue1", forKey: "DemoAttribute1") event.addAttribute("DemoAttributeValue2", forKey: "DemoAttribute2") event.addMetric(NSNumber.init(value: arc4random() % 65535), forKey: "EventName") pinpointAnalyticsClient.record(event) pinpointAnalyticsClient.submitEvents() }

Build, run, and try your app, and then view your custom events in the Events tab of the Amazon Pinpoint console (use your Mobile Hub project / Analytics > Amazon Pinpoint console / Analytics > Events). Look for the name of your event in the Events dropdown 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.

Android - JavaAndroid - KotliniOS - Swift
Android - Java
import com.amazonaws.mobileconnectors.pinpoint.analytics.monetization.AmazonMonetizationEventBuilder; public void logMonetizationEvent() { final AnalyticsEvent event = AmazonMonetizationEventBuilder.create(pinpointManager.getAnalyticsClient()) .withFormattedItemPrice("$10.00") .withProductId("DEMO_PRODUCT_ID") .withQuantity(1.0) .withProductId("DEMO_TRANSACTION_ID").build(); pinpointManager.getAnalyticsClient().recordEvent(event); pinpointManager.getAnalyticsClient().submitEvents(); }
Android - Kotlin
import com.amazonaws.mobileconnectors.pinpoint.analytics.monetization.AmazonMonetizationEventBuilder; public void logMonetizationEvent() { pinpointManager?.analyticsClient?.let { val event = AmazonMonetizationEventBuilder.create(it) .withFormattedItemPrice("$10.00") .withProductId("DEMO_PRODUCT_ID") .withQuantity(1.0) .withProductId("DEMO_TRANSACTION_ID").build(); it.recordEvent(event) it.submitEvents() } }
iOS - Swift
func sendMonetizationEvent() { let pinpointClient = AWSPinpoint(configuration: AWSPinpointConfiguration.defaultPinpointConfiguration(launchOptions: nil)) let pinpointAnalyticsClient = pinpointClient.analyticsClient let event = pinpointAnalyticsClient.createVirtualMonetizationEvent(withProductId: "DEMO_PRODUCT_ID", withItemPrice: 1.00, withQuantity: 1, withCurrency: "USD") pinpointAnalyticsClient.record(event) pinpointAnalyticsClient.submitEvents() }