Wednesday, October 31, 2018

Adobe Experience Platform SDK Setup (iOS)

There were 178 billion apps (statista) downloaded in 2017. With that amount of volume, it'll be unthinkable for any major organization today to not have a mobile app that allows existing and potential customers to interact with its brand. Most Apps regardless of their purpose have some kind of analytics tracking embedded in them and one of the tracking solutions they leverage is Adobe Analytics.

Adobe Experience Platform SDK (informally known as SDK V5.0) was recently launched and it aims to give clients more flexibility around mobile SDK deployment as it leverages Launch by Adobe to publish changes in an external environment outside of the native app. This was not the case with the previous version v4 of the SDK. The reason why that's exciting is because any configuration changes to the SDK around Analytics can now be done in Launch without having to go through the App Store. There are other differences between the two versions which is covered in more detail here.

There are two primary methods to setup the AEP SDK which are either using CocoaPods or the manual method but in this post, I'll cover how to set this up manually. A lot more information is provided in the Mobile team's official documentation but my aim is to take their instructions and document it visually using my sandbox. I'm covering two main components of this setup which leverage Launch by Adobe and XCode (V10) to setup the SDK.

Launch by Adobe Setup

This is a big enhancement of this SDK over V4.0 where we're now able to deploy the configuration library using Launch by Adobe as opposed to the ADBMobile.json config file that we have with V4.0. The primary advantage of this is that we're able to make basic configuration changes such as changing report suites, enabling/disabling tags, activating the Experience Cloud ID service etc. directly in Launch without having to go through the App Store. There will obviously be a need to publish the app at the start to the App Store to submit the app. Please note that we currently cannot setup any trackAction (clicks) or trackState (page views) calls in Launch and need to do that directly in the App so that does require us to to go through the App Store for each change. Let's go through the steps.
  • Create a mobile property in Launch and select the platform as Mobile.

  • We then setup extensions in Launch and by default, you should see two extensions already added called "Mobile Core" and "Profile" which are explained below. I'm not going to cover these in detail as we only need to add some basic details to the Mobile Core extension. Additionally, we also need to add the Adobe Analytics from the Catalog and install it. Let's review these extensions.
    • Mobile Core: This provides essential SDK related functionality as well as the library to deploy the Experience Visitor ID service
    • Profile: It stores user attributes on the client and more details can be found here
    • Adobe Analytics: It provides the Adobe Analytics library to the SDK. 

Add your tracking server

Add your report suite and tracking server
  • Once we've installed the extensions, we need to retrieve the iOS libraries that are accessible in the Environments section in Launch. This snippet contains a reference to libraries that need to be included in XCode to deploy the SDK (see below). 

  • Finally, we need to publish these extensions to either the development or production environment depending on the scenario. Note that you can also disable Analytics tags from the App by publishing it in Launch if required.

XCode Setup

Before diving in, I highly recommend that you review the steps outlined in Adobe's official documentation on configuring the SDK. Some of what I'll cover is outlined in the documentation but I'm including a lot more detail in the form of screenshots from XCode which the documentation doesn't include. So, let's continue.

  • Download XCode and setup a basic App which allows you to simulate an iOS App experience.

  • Download the AEP iOS SDK from Adobe Experience Platform's Github branch located here.

  • The downloaded zip contains a bunch of files and folders but the one we need to use is called "iOS" which contains two sub folders called "device-only" and "universal". 

  • The "iOS" folder needs to be added to XCode and mapped to the Target in XCode. Once the mapping is done, we need to add some frameworks to the "Embedded Libraries" section in XCode to provide the necessary libraries to the SDK. Please note that for an actual iOS Apps, you need to use the frameworks present in "device-only" but for Simulators (my use case), you need to use the frameworks present in the "universal" folder. I've tried to color code the relevant details in this screenshot.

  • Once the required frameworks are added, we need to reference all libraries and call specific methods to activate lifecycle calls, enable logging and other methods as explained here. I'm using Objective C but the documentation covers Swift and Android syntax as well. Please note that I copied the installation code directly from the Environments section in Launch (covered above) and included it in XCode which ties the SDK with Launch. I've included these methods in the AppDelegate.m file of my App. The integration with Launch is done via the configureWithAppID call to which we pass the Launch App/Environment ID.

  • Once the basic lifecycle tracking methods are added, we can add a trackState (page view) method call to trigger an event. I'm basically sending data to the "screenName" variable populated with a value of "homeview". That is typically done in the ViewController.m file.

  • Finally, we need to make sure that the App build is successful and test the Analytics call. In my case, I'm looking for the variable called "screenName" which is populating in the debugging console as shown below.

The Adobe Experience Platform SDK is still relatively new and is being evolved but the process of installing the SDK is fairly easy once you get through the initial learning curve. I will continue to keep track of all upcoming features and will write about other functionalities tied to Launch by Adobe to trigger different types of mobile events.

No comments: