Experience League | Image

Expand the Possibilities of Adobe Experience Platform with Mobile SDK Extensions

Adobe SUMMIT 2019 - Lab 781

Figure 1: Adobe Experience Platform Logo

Figure 1: Adobe Experience Platform Logo

Table of Contents

Introduction - Lab Overview

The latest generation of the Adobe Experience Platform Mobile SDK was built from the ground up to be modular and extensible. Extensions allow partners and customers to augment, customize and extend the capabilities of the Adobe Experience Platform SDKs with their own code. This includes listening for and dispatching any mobile engagement event, reading the shared state of any registered extension, and sharing the state of the current extension. The value of extensions for both customer and partners include:

  • By utilizing an Adobe Experience Platform extension vs. implementing a native SDK integration, there is less work on the customer’s part to install and initialize third party solutions and fewer API calls they need to implement.

  • Extensions that integrate with the Adobe Launch rules engine provide customers additional capabilities in constructing complex use case workflows across multiple solutions.

  • Extensions are managed within the Adobe Launch portal and can be dynamically updated with configuration changes without requiring a customer rebuild or resubmit their application. In this lab we will create a new mobile extension that will retrieve weather conditions based on zip code and will post back requested weather conditions to a slack channel. Each request will also register a data point on our combined weather map report.

Key Takeaways

By the end of this lab, participants should have a good understanding of:

  • What is new with the Adobe Experience Platform Mobile SDK
  • How the Mobile SDK integrates with Adobe Launch
  • What the opportunity is for partners and customer to create their own extensions
  • What the different components are of an Adobe Experience Platform Mobile SDK extension
  • How to create a native extension that interacts with Adobe Experience Platform Mobile SDK Core
  • How to create an Adobe Launch UI extension to capture configuration parameters, events, conditions and actions
  • Where to go for additional resources related to the Adobe Experience Platform Mobile SDK

Terminology

Some terms and language that may discussed as part of this lab:
  1. Client-side – In this lab we will refer to the portion of the mobile extension that will be built to be directly integrated into the mobile application as the Client-side extension.
  2. Launch UI extension – In this lab we will refer to the portion of the mobile extension that is installed and configured in the Adobe Launch portal as the Launch UI extension.
  3. Mobile Core event hub – The Mobile Core event hub will track all mobile lifecycle events based on end-user engagement and will publish these events to all registered extensions.
  4. Event listener – Mobile extensions can register an event listener to get notifications for events that occur in the Adobe Experience Platform Mobile SDK. Developers can then add logic to their extensions to be executed based on events.
  5. Shared States – Shared states are events that contain data that can be exposed and shared to other registered extensions. Shared state data keys can also be used as rule actions in various workflows. Shared state data can be updated multiple times by an extension and it is persisted for the duration of current session; when the mobile application is restarted, all the shared states will be cleared.
  6. Reactor Scaffold tool – A Launch UI extension building service that will create a framework of files that can be modified and then packaged up to create the extension package to be uploaded into Adobe Launch.
  7. Reactor Sandbox tool – Reactor Sandbox will package up your locally developed Launch UI extension and will allow you to view and test it within a web browser at http://localhost:3000
  8. Adobe I/O integration – An Adobe I/O integration is required for any partner or customer that wishes to upload an extension. Creating an Adobe I/O integration includes creation of private and public keys and certificates to link your extension with your company organization.
  9. Private extension – Extensions that have not been made public, are private to the company organization that they will uploaded to. Only Launch properties that have been defined for extension development will show private extensions.
  10. Public extension – Extensions that have been published to the public catalog and are available to all users of Adobe Launch. An extension developer must fill out a request form for Adobe to move your extension from private status to public.

Prerequisites

  • Client-side native iOS extension code examples will utilize Apple Xcode v10.x with and iPhone Simulator running iOS 10+.

  • Customers and Partners should have access to Adobe Launch, along with the ability to create and manage mobile properties.

    If you cannot create a mobile property, or do not have access to Adobe Launch, reach out to someone in your organization that can grant you access rights through the Adobe Admin Console. See this guide for more information: Assigning User Permissions.

  • Node.js 5.2.0 or greater is required for this lab. If it is not installed, the latest version can be found here.

  • Optional - create an Adobe I/O integration.

Get updated

Beyond this Adobe SUMMIT lab, we are continuously updating our example projects. Visit or bookmark the following Github projects below to see our latest progress:

Components of an Adobe Experience Platform Mobile SDK Extension

Figure 2: Adobe Experience Platform Mobile extension components

Figure 2: AEP SDK extension components

Each Adobe Experience Platform SDK extension is comprised of two components, a client-side native extension that is implemented inside the application, and a Launch UI extension that is uploaded into the Launch extension catalog and can be used to set configuration values. Beyond capturing configuration values, the Launch UI extension can expose events, conditions and actions that can be used in the Launch rules engine for workflow automation.

Adobe Experience Platform Mobile SDK Core event hub

Figure 3: Adobe Experience Platform Mobile SDK Core event hub

Figure 3: Adobe Experience Platform Mobile SDK Core event hub

Looking at the Mobile SDK Core event hub process flow you can see that as users engage with the mobile application, events are received by the Mobile Core event hub and are then simultaneously dispatched to all extensions that have registered event listeners.

Module 1 - Modifying the Client-Side Weather Extension

Lesson 1 - Implement a mobile extension

Objective

  1. The objective of this lesson is to get familiar with the main components of a client-side iOS extension using Experience Platform Mobile SDK.
  2. Find out how the extensions are dispatching new events through the Mobile SDK event hub and receiving new events from the public APIs or other extensions.
  3. Learn how to update a shared state for a mobile extension.
  4. Register the mobile extension with the event hub in order to receive events from the Mobile SDK event hub.

Lesson Context

As part of this lesson, a new mobile extension will be implemented in order to retrieve the weather conditions from a server based on a zip code. Adobe Mobile SDK team has provided sample code which can be used for this lesson.

Exercise 1.1

Implement an iOS mobile extension for retrieving the weather conditions for a zip code.

  1. Open the project in Xcode: Navigate to the resources/module-1/ACPWeatherExample directory and double click on ACPWeatherExample.xcworkspace. The ACPWeatherExample project should open in Xcode.

    Hint: From the Project navigator you will see two projects, ACPWeatherExample and Pods. The ACPWeatherExample project contains the implementation for the weather extension and a test application for this lesson. Pods project contains the installed Cocoapod dependencies for this project: ACPCore representing the Mobile SDK Core extension and ACPAnalytics which is the Adobe Analytics mobile extension.

    Figure 4: ACPWeatherExample Xcode project structure

    Figure 4: ACPWeatherExample Xcode project structure

  2. Once the project is opened in Xcode, search for the keyword TODO in the project in order to see all the steps for this lab exercise. It is recommended to implement these steps in incremental order. Each step has a number which is associated with the exercise number (module#.lesson#.exercise#).

    Click on the search magnifier and in the text filed type TODO.

    Figure 5: Find the steps to be implemented

    Figure 5: Find the steps to be implemented

  3. One of the required methods to override in a Mobile extension is the "name" method. This method should return the extension name. This name is used by the Mobile SDK Core as the extension's shared state name and also can be used for logging purposes. Multiple extensions can be registered at the same time with the Mobile SDK event hub, so the extension should have a unique name in order to avoid name conflicts. For the weather extension the following name should be set (Step 1.1.3.):

  4. Next, the extension needs to register an event listener in order to receive events from the event hub with a particular event type and event source. The WeatherExtensionListener class should be provided as parameter (Step 1.1.4.):

  5. Implement the WeatherExtensionListener class by first queueing the received event and then start processing the existing events. Introduce the following two lines where indicated (Step 1.1.5.):

    Hint: We are queuing the received event in order fetch the latest Configuration shared state for current event. If at the time of processing the event the Configuration shared state is not updated (for example is nil because the remote download is not completed yet), we are keeping the event in the queue until a shared state update event is received from the event hub when we will retry to process this event.

  6. When processing the event, after extracting the zip code from the request event, a network call is made to request the weather conditions. The following line needs to be uncommented where indicated (Step 1.1.6.):

    Updating extension's shared state allows other extensions to access the latest weather conditions and these values can be used as data elements when rules are triggered, as it will be exemplified later in this lab.

  7. After the weather conditions are received, also send a response event. You can create an event by using ACPExtensionEvent as follow (Step 1.1.7.):

  8. Once the event is created, it should be dispatched to the event hub using

    ACPCore dispatchResponseEvent:requestEvent:error: API. This API dispatches a response event for the associated request event (the trigger for this response). Uncomment the following line (Step 1.1.8):

    Read more about this here: Dispatch paired events

  9. The following 3 steps implement the two public APIs for the Weather extension that the mobile application developer will be interacting with.

    First, let's implement the registerExtension API. When this API is called the internal extension (WeatherExtensionInternal class) should be registered with the event hub. Calling ACPCore registerExtension API allows the event hub to register the extension. Uncomment the following line (Step 1.1.9.):

  10. The second public API getWeatherByZipCode:callback: receives the zip code as parameter from the mobile application developer and has a response callback function for the weather conditions. In order to send the zip code to the WeatherExtension create a request event with the same event type and source as the registered WeatherExtensionListener (see Step 4) and attach the zip code as event data as follows (Step 1.1.10.):

  11. Dispatch the getWeatherEvent to the event hub and implement the response callback to return the weather conditions back to the mobile application.

    The ACPCore dispatchEventWithResponseCallback:responseCallback:. API allows you to dispatch an event to your extension and wait for a response event in return. Uncomment the following line (Step 1.1.11.):

  12. Last step, build the project. If everything was implemented correctly, there shouldn't be any compilation errors.

    To Build the Weather Extension, from the Xcode top bar select the ACPWeatherExample target and an iPhone simulator, for e.g. iPhone XR (the selected iPhone should have iOS version 10+), then click on the Run button (play button) or press ⌘B.

    Figure 6: Build the ACPWeatherExample

    Figure 6: Build the ACPWeatherExample

Lesson 2 - Integrate extensions in a mobile application

Objective

  1. The objective of this lesson is to utilize the Weather Extension created in Lesson 1 in an iOS mobile application.
  2. As part of this exercise, you will learn how is the Adobe Mobile SDK configured by a mobile developer and how various extensions can be registered when the application is initialized.

Lesson Context

For this lesson the provided TestApp will be used to test the Weather Extension implemented in Lesson 1.

Note: If for some reason you were not able to finish the exercise in Lesson 1, you can use the finished project located at resources/module-1/ACPWeatherExample-finished. Close the current Xcode project and then double click on ACPWeatherExample.xcworkspace.

Exercise 1.1

In this exercise, you will run the iOS TestApp in order to see the Weather extension dispatching events through the event hub, fetching response events and displaying the weather conditions in the mobile application. This application is an example of how an Adobe Mobile SDK customer can integrate Adobe and partner extensions in the same application, and how the Weather Extension will be used by the application developer.

  1. For this exercise we are going to work with the TestApp folder in the Xcode project. In the project structure on the left side of your Xcode, click on TestApp to see the sources.

    Figure 7: Test application sources

    Figure 7: Test application sources

    As you can see in Figure 7, the TestApp has sources and headers for AppDelegate and ViewController.

  2. Check the AppDelegate.m source code (in the left tab, click on this file). The following method - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions will be called when the application is initialized/booted.

    The first step is to configure the Adobe Mobile SDK by using ACPCore configureWithAppId: API and providing the Launch configuration ID for the environment that you are using (production, staging, development). This is a unique identifier that Launch UI provides for a mobile property, which will be used by the Adobe Mobile SDK to download the remote configuration and the rules configured for this property.

    After that, all the extensions are registered with the event hub as follows:

    Finally, ACPCore start method is called in order to start processing the events:

    Note: It is important to register the extensions before calling ACPCore start API in order to receive all the events. Since the system is asynchronous, registering the extension after ACPCore start call may result in some events being dispatched before the extension is registered.

  3. Check the ViewController.m source code (in the left tab, click on this file), it contains two on click button actions associated with the two buttons in the app.

    The first one, getWeather calls the WeatherExtension getWeatherByZipCode:callback: public API that was implemented in Lesson 1, Exercise 1.1 and updates the UI of the mobile application with the returned weather conditions.

    The second one, getWeatherByTriggeringRules calls the ACPCore trackAction API with current zip code value. The event generated by this API call will be used by the Adobe Analytics mobile extension in order to track the click button action and it can be used for triggering new rules configured in Launch UI for this mobile property.

  4. In order to run the test application, from the Xcode top bar select the TestApp target and any iPhone simulator, for e.g. iPhone XR (the selected iPhone should have iOS version 10+), then click on the Run button or press ⌘B.

    Figure 8: Run the TestApp which uses the Weather Extension

    Figure 8: Run the TestApp which uses the Weather Extension

  5. Once the iOS mobile application is installed and opened on the selected iOS simulator, write the preferred US zip code and click on the Get weather button. The results should looks as in the image below:

    Figure 9: Test Application running

Module 2 - Modifying the Launch UI Weather Extension

Lesson 1 - Test the Launch UI extension in the Reactor Sandbox tool

Objective

  1. The goal of this lesson is to become familiar with testing your Adobe Launch Mobile extension in a local sandbox environment.
  2. When launching an extension in sandbox mode a user will be able to see what configuration values are being captured and any defined events, conditions or actions.

Lesson Context

Every Adobe Experience Platform Mobile SDK extension has both a client-side component and a Launch UI extension component. The Launch UI extension is used to capture configuration values necessary to allow the client-side extension to work. Additionally, the Launch UI extension can be developed to expose events, conditions and actions specific to the extension. When defined, these actions can be used in the Launch rules engine.

Local sandbox testing is recommended for any Launch UI extension before uploading it to the Adobe Launch private or public catalog.

Exercise 1.1

In this exercise we will startup the local Launch sandbox environment and view the Launch weather extension.

  1. Launch Terminal from the application dock, or by navigating to Applications/Utilities/Terminal.app

  2. Open the folder: /resources/module-2/

  3. In Terminal type cd then drag and drop the weather-extension directory from /resources/module-2/ path.

    Figure 10: Navigating to the weather-extension directory

    Figure 10: Navigating to the weather-extension directory

  4. If you type pwd and return you should see in terminal that you are now located inside the weather-extension folder.

    $ pwd
    
  5. On a new line in Terminal type: npx @adobe/reactor-sandbox and hit return:

    $ npx @adobe/reactor-sandbox
    
  6. You should see a message saying: 'Extension sandbox running at http://localhost:3000 and at https://localhost:4000'

  7. Launch Chrome from the application dock and type in http://localhost:3000. You should now see the Weather Extension running in sandbox mode.

  8. In the Select View drop-down make sure that Extension Configuration is selected.

  9. Notice that the sandbox shows a Timeout field. Type in a value i.e. 200.

    Figure 11: Running Launch Weather Extension in Sandbox

    Figure 11: Running Launch Weather Extension in Sandbox

  10. On the right side of the window, select the tab named Get Settings and hit the Get Settings button. This should show the Timeout value that you typed into the field.

  11. At the bottom of the Get Settings window you can also click the Copy Settings to Init Panel button.

  12. Click back on the Init window and see that "weather.timeout" has a value equal to what was entered into the field.

    Hint: the sandbox can be used to see how the Launch extension custom views will look like in Adobe Launch dashboard and what will be the returned values for the provided callbacks: init(), getSettings() and validate() before publishing the extension. These methods will be detailed in Lesson 2.

Lesson 2 - Modify the Launch UI extension to add an API key field

Objective

  1. The objective of this lesson is to show how additional configuration parameters can be added to a Launch UI extension, which then can be passed to a client-side mobile extension.

Lesson Context

Now that we have seen how the Launch local sandbox can be used to preview and test your Launch UI extension, it's time to add an additional configuration field to the Weather extension.

Exercise 1.1

In this exercise we will add an API key field to the Weather extension and then preview the changes in Launch Sandbox mode.

  1. From the Finder navigate to the folder:

    /resources/module-2/weather-extension/src/view/configuration

  2. Find the configuration.html file and drag and drop this file over the Brackets application.

  3. To Add a new configuration key, add a new label in the . Un-comment out lines 11-18 by removing the "" HTML comments (Step 2.2.3):

  4. Add your key in the init function to populate the view with info.settings which will exist if the user is editing something that was previously saved.

    Further down in the same file on line 36 remove the "//" comment (Step 2.2.4):

  5. Next, add your key in the return of the getSettings function. These keys should contain the values added by the user. The same keys can be used when the remote configuration is downloaded by the Adobe Mobile SDK when the application is launched and handled in the mobile extension.

    Also remove the "//" comments on lines 47 and 50 (Step 2.2.5):

  6. Last, update the validate function with some restrictions for the new key. This will guide the user to configure the extension properly.

    Remove the "//" comments on lines 63-66 (Step 2.2.6):

  7. Save and close this file.

  8. Click back on the Chrome browser and refresh the Launch Sandbox at http://localhost:3000.

  9. If you accidentally stopped the Sandbox, then go back and repeat the steps in the previous Lesson 1 to launch the Weather extension in Sandbox mode.

  10. You should now see the API Key field in the extension configuration view as in the image below:

    Figure 12: Weather Extension API Key in Sandbox

    Figure 12: Weather Extension API Key in Sandbox

Next Steps

Beyond the baseline extension created in this lab, take some time to explore the Launch UI extension further to see how we were able to define Data Elements, Events, Conditions and Actions that are all used in the Launch rules engine.

When you are ready to upload your extension to the Adobe Launch catalogue, you will first need an Adobe I/O integration created. See this documentation for how to create the integration here.

Appendix - Resources

There is a great deal of information available to learn more about the Adobe Experience Platform Mobile SDK and Launch. Below are some resources that may be helpful: