AWS Pinpoint Tutorial for iOS: Getting Started

Most developers will agree that mobile app analytics information can be invaluable. Knowing how long a user stays on a screen, which UI/UX experiments work best, or what users like to spend money on can help you make more informed decisions to improve your apps. If you’re not using an analytics tool or find your current tool lacking, you should consider introducing analytics into your development practices as soon as possible.

Amazon’s previously separate AWS mobile analytics tool has since been rolled into Amazon Pinpoint. This tutorial will help you get started with AWS Pinpoint app analytics for iOS.

If you’re curious about the general ins and outs of mobile analytics, you can read through the precursor to this tutorial here to get caught up: Getting Started with Mobile Analytics

You’ll need to have an AWS account for this tutorial. If you don’t have one yet, you can get started with an AWS account here; simply look for the Create A Free Account link.

You will also need a credit card to set up your account as a safeguard. You will not get charged as long as you are within the free daily allotment of 100,000,000 analytics events.

Getting Started

Use the Download Materials button at the top or bottom of this tutorial to download the starter project.

This project builds upon the Beer Tracker app from a previous tutorial. The app lets users keep track of and rate their favorite beers. For this tutorial, you’ll add analytics to understand what users are actually doing when they are using your app.

Setting Up the AWS Account

Your first task is to cloud-enable your app so it can interact with AWS services. Once you have an active AWS account, head to the AWS Console.

Click on the Services dropdown. Then click on the Mobile Hub service. You’ll arrive at the following page:

Follow the steps below to cloud-enable your Beer Tracker app with AWS Mobile Hub service:

1. Click Create. Set Your Project Name to Beer Tracker. Tick the Allow AWS Mobile Hub to administer resources on my behalf box. Click Next.
2. Select iOS as the platform and then click Add. This will add AWS cloud services to your app.
3. Click Download Cloud Config. You’ll use this cloud configuration file in your Xcode project. Then click Next.
4. The starter project has integrated the AWS Mobile SDK for you. Simply click Done.

Once you have cloud-enabled your app, you should now see a screen that looks like this:

Integrating Pinpoint in Xcode

Open the starter project by selecting BeerTracker.xcworkspace. The app uses CocoaPods and has integrated the Pinpoint SDK into your project. Build and run the app, and take a look around.

Note: If you have any build issues, you may need to reinstall the pods. Navigate to your project’s directory in Terminal, and run pod install. You can learn more about getting started with CocoaPods here.

The Beer Tracker app allows users to record the following details about the beer they consume:

• Name
• Rating
• Photo
• Any notes about it

While this seems fairly straightforward, it may be unclear to you how much users actually interact with each of these features. Is it worthwhile to keep investing in your current UI? Would it make sense to give your app a new look and feel? Adding analytics may help you answer these questions, and more.

First, you’ll need to add the awsconfiguration.json file you downloaded earlier to the project. Drag the file to the Supporting Files group. Ensure that Copy items if needed and Add to targets are both selected. Click Finish. You should be able to see the file in the Supporting Files group:

This file contains all the information needed for the Pinpoint SDK to properly set up its connection to AWS. Open awsconfiguration.json and you’ll see information about the region, the Cognito PoolId, and the AppId used for your app.

Open AnalyticsManager.swift and you’ll see some existing code. Add the following method to AnalyticsManager:

func setupClient(withLaunchOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) {
  pinpoint = AWSPinpoint(configuration:
    AWSPinpointConfiguration.defaultPinpointConfiguration(launchOptions: launchOptions))
}

Simply, this code sets up the pinpoint property to be used throughout the app.

Next, open AppDelegate.swift, and add the following right after the existing import:

import AWSPinpoint

Now replace application(_:didFinishLaunchingWithOptions:) with the following:

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
  // 1
  AWSDDLog.sharedInstance.logLevel = .verbose
  // 2
  AWSDDLog.add(AWSDDTTYLogger.sharedInstance)
  // 3
  AnalyticsManager.shared.setupClient(withLaunchOptions: launchOptions)
  return true
}

Here’s what you’ve added:

1. You turned on the logging feature of the AWS SDK platform. By setting the log level to .verbose, you’ll see every log statement that is produced by Pinpoint or any other AWS services available.
2. You set the AWSDDLog to print to your Xcode console. You’ll see this in action soon.
3. You set up the AnalyticsManager using the code you added previously.

Build and run the app, open the debug area, and you should see the following in the console:

With that, you’re all set up to use the Pinpoint SDK.

Pinpoint Analytics Events

Pinpoint can track several different types of analytics events to help you understand what’s going on in your app:

• Custom events
• Monetization events
• Authentication events
• Session events

You’ll focus only on the first two types — Custom and Monetization events — in this tutorial. However, if you look into the documentation of the other two events, you’ll see that they aren’t too different from the ones covered here.

Adding Custom Events

The first thing you’ll track is the number of people adding a beer record in your app. To do this, you’ll need to create a custom event.

First, open AnalyticsManager.swift, and add the following method to AnalyticsManager:

func create(event: String) {
  guard let pinpoint = pinpoint else { return }
  // 1
  let event = pinpoint.analyticsClient.createEvent(withEventType: event)
  // 2
  pinpoint.analyticsClient.record(event)
}

Here’s what you’ve added:

1. You’ve created an event with the provided event type. This is all you need to do to create a custom event.
2. Here, you’ve recorded the event. Take notice that you haven’t actually uploaded the event to Pinpoint, just saved it for later. Pinpoint will save these events, even if the app is closed, to be uploaded later.

Open BeerDetailViewController.swift, and add the following to the end of viewDidLoad():

AnalyticsManager.shared.create(event: Event.visitedBeerDetailViewController)

Here, you call create(event:) with the Visited BeerDetailViewController event type.

Build and run. Before you navigate anywhere in the app, clear the console by clicking on the Trash icon in the lower right of the console. In the app, tap on the + button in the upper-right corner. Check the console, and you’ll see that a saveEvent log is added along with its event type.