Moving Billboard Captured in Times Square

Analytics are no longer an option for mobile developers — they’re a requirement if you want your app to succeed.

Analytics play a huge role in two of the most important areas for mobile app growth and success: acquisition and retention. Acquiring iOS customers is expensive. The moment you gain that customer, retention efforts must begin.

To retain iOS customers, you need to understand and engage them. Understanding customer segments and behavior are key to defining the right customer experience.

In this article (1 of 3), I’ll walk you through collecting user demographics and app session activity to better understand customer platforms and behaviors. In the following articles, we’ll explore customer segments and messaging channels to engage those customers based on the behaviors and demographics we are about to collect.

How it Works

We’ll start with an existing offline app and then cloud-enable it using the AWS Amplify CLI which provisions cloud resources and configures the iOS client for sending analytics events to the cloud.

Start Local

You don’t need to create any services in the cloud to get started with analytics. I started by defining a protocol (Swift for “interface”) for analytics:

Here’s a LocalAnalyticsService class implementation that adopts and conforms to the AnalyticsService protocol above:

The final step before I can use this analytics module is to create an instance of the service. In this example, I’m using the AppDelegate.swift file to instantiate a local analytics service:

Now I can record events anywhere I want. First, get a reference to the service (generally in the init() or viewDidLoad() ), and then call the recordEvent() function to record an event:

When you run your app, you will see the analytics events printed out in the debug log within Xcode. Remember, we are still local but the nice thing about doing it this way is that you can easily swap out the implementation with a real analytics service without making any UI code changes! Now, let’s go from local analytics to Amazon Pinpoint analytics.

Add Analytics Service using Amazon Pinpoint

First, install and configure the AWS Amplify CLI. There are detailed instructions plus a video on the AWS Amplify website to get started.

Once the Amplify CLI is installed and configured, open a terminal to your iOS project directory (the folder with the Project.xcodeproj file).

First, initialize the project:

$ amplify init

You’ll be guided through the process, which includes naming the project, confirming that you are developing an iOS project, and choosing appropriate credentials for deploying resources to AWS. This command will create an / amplify directory to store the details of the backend. Now, let’s add an Amazon Pinpoint resource for storing analytics:

$ amplify add analytics

You can press enter to progress through the process. All the defaults are good for this app. Finally, let’s deploy the resources:

$ amplify push

You’ll be asked to confirm the deployment and then the resources are created.

What just happened?

To enable our app to send analytics to be stored in the cloud, we first initialized an iOS project to be cloud-enabled using the AWS Amplify CLI. The CLI then created a new Amazon Pinpoint application with the appropriate permissions for your iOS app to send analytics events. The CLI then created an awsconfiguration.json file with the Amazon Pinpoint endpoint and region. I’ll show you how to add this configuration file to your Xcode project below.

Add the AWS SDK for iOS to your project

The AWS SDK for iOS contains all the code necessary for connecting to AWS cloud resources, including Amazon Pinpoint. I use Cocoapods to load library dependencies. First, initialize Cocoapods for your project:

$ pod init

This will create a blank Podfile . Edit the file to include the Amazon Pinpoint library and save. Note: Make sure the target name matches your iOS app name:

$ pod install --repo-update

Now close down Xcode and open up the workspace version of the project:

$ open <yourprojectname>.xcworkspace

Do a quick build to compile the new libraries.

Integrate the awsconfiguration.json file

When using the AWS Amplify CLI to provision backend resources, it produces a file called awsconfiguration.json in the root of your iOS project. This file contains a description of the resources that you can access via your app and is updated (synced) with your project anytime a resource is added, updated, or deleted by the CLI. This one of the great benefits of using the Amplify CLI to provision resources for your project.

You need to add the awsconfiguration.json file to your Xcode project just once. You can do this by dragging it to your Finder in the Xcode project organizer.

You will be prompted if you want to copy the file. UNCHECK THE COPY ITEMS BOX. The AWS Amplify CLI updates this file when things change. If you check the Destination box, then your project may not receive the updates if copied. If you uncheck the box, this file is updated by the AWS Amplify CLI whenever you modify the project resources via the Amplify CLI.

Create a new AWSAnalyticsService

Now we can create a new analytics cloud service that replaces our local analytics service.

Add this class to your Xcode project:

The init() method initializes the AWS SDK for Amazon Pinpoint using the constants defined in the awsconfiguration.json file. Initializing the Pinpoint client triggers the SDK to automatically begin tracking app session data and user demographics without any developer code. The recordEvent() method is an implementation for sending custom events to Pinpoint. You can view these aggregated events in the Pinpoint console under the Analytics > Events tab.

All that is left is to swap out the local analyticsService in the AppDelegate.swift file with the AWS analyticsService.

Change LocalAnalyticsService() to AWSAnalyticsService() .

View Analytics in Amazon Pinpoint Console

Once you run your app and do some stuff to generate user analytics and custom event traffic, you can open up the Pinpoint console using the Amplify CLI:

$ amplify analytics console

You may be asked to log in to the console — just use your AWS credentials. You will be placed directly into the analytics tab of the Pinpoint application and can start exploring the graphs.

Recording Custom Events

By default, the Amazon Pinpoint SDK automatically collects user demographics and app session activity without any additional code. However, if you want to collect non-default events, it’s common to add app-specific custom analytics events, like milestones, game level achievement, or revenue events. If you’ve implemented in-app purchases, then you probably want to add a recordRevenue() function to the protocol (and hence the concrete implementation). This is great for viewing live updates (on the Pinpoint console) of how much money you’ve made through in-app purchases.

You can also augment the user demographics events with auxiliary information, like the currently authenticated user, location of the device, and other custom fields. The more we collect now, the better our user segments will be for targeted engagement. So, take a moment and figure out what you’d like to collect and try it out. We’ll be using those customer segments in the later articles when we talk about targeted engagement through communication channels such as push notifications, sms, and email.