This extension enables in-app messaging, push notifications, and marketing links functionality from Mobile Services on the Experience Platform SDK.

Review the following Mobile Services functionality documentation for context and set up before implementation at these links:

• ​Getting started with Mobile Services​

• ​Create and managing apps​

• ​Acquisition and marketing links​

• ​Push and in-app messaging​

To use the Mobile Services extension, complete the following steps:

1. Configure the Mobile Services extension in Launch.

2. If using acquisition and marketing links, update your configuration in the Analytics extension.

3. Add Mobile Services extension to your app.

4. Implement the Mobile Services APIs in your app.

Configure the Mobile Services extension in Experience Platform Launch

Automatic configuration (Recommended)

1. In Experience Platform Launch, click the Extensions tab.

2. Choose Catalog, locate the Adobe Analytics – Mobile Services extension, and click Install.

3. Select a Mobile Services app and complete the following tasks:

   1. In Mobile Services app, select app from the drop-down list.

   2. Click Save.

   3. Follow the publishing process to update the SDK configuration.

Manual configuration

To install the Mobile Services extension, complete the following steps:

1. Select Enter Custom settings.

2. Enter an Acquisition time out. The recommended time out is 5 seconds. To enable app acquisition, this value must be greater than 0.

3. Provide the Acquisition App ID (sample value: 0eb9f2791f0880623f91e41e5309d2ae25066e513054a4cb59168dc886b526da)).

   You can find the Acquisition App ID in Mobile Services.

4. Select your app, navigate to Manage App Settings page, and in the SDK Acquisition Options section, copy the hashed string similar to the highlighted value:

   ​​

5. Provide the Messages URL. This value would look something similar to: https://assets.adobedtm.com/b213432c5204bf94318f4ef0539a38b487d10368/scripts/satellite-5c7711bc64746d7f5800036e.json

   You can find the Messages URL from your ADBMobileConfig.json file typically near the bottom of the file.

   ​​

6. Click Save.

7. Follow the publishing process to update your SDK configuration.

Configure the Adobe Analytics extension

1. To ensure that this extension is correctly configured and implemented, follow the steps in the configure the Mobile Services extension in Experience Platform Launch tutorial.

2. In Launch Hit Delay, type a value of 5s or more to ensure that the acquisition context is sent to Analytics with your Lifecycle information.

Add the Mobile Services extension to your app

import com.adobe.marketing.mobileservices.*;

#import "ACPCore.h"
#import “ACPIdentity.h”
#import “ACPLifecycle.h”
#import "ACPAnalytics.h"
#import "ACPMobileServices.h"

import AEPCore
import AEPIdentity
import AEPLifecycle
import AEPAnalytics
import AEPMobileServices

Register Mobile Services with Mobile Core

public class MobileServicesApp extends Application {
​
@Override
public void onCreate() {
     super.onCreate();
     MobileCore.setApplication(this);
​
     try {
             Analytics.registerExtension();
MobileServices.registerExtension(); //Register Mobile Services with Mobile Core
Lifecycle.registerExtension();
             Identity.registerExtension();
             MobileCore.start(null);
     } catch (Exception e) {
     //Log the exception
     }
  }
}

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   [ACPAnalytics registerExtension];
   [ACPLifecycle registerExtension];
   [ACPIdentity registerExtension];
   [ACPMobileServices registerExtension];
   [ACPCore start:nil]
   // Override point for customization after application launch.
   return YES;
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    MobileCore.registerExtensions([Signal.self, Lifecycle.self, Analytics.self, Identity.self, AEPMobileServices.self ], {
        MobileCore.configureWith(appId: "yourLaunchEnvironmentID")
          MobileCore.lifecycleStart(additionalContextData: ["contextDataKey": "contextDataVal"])
    })
  ...
}

Implement Mobile Services APIs in your app

To use your Android or iOS extension with the Experience Platform SDKs, implement the following APIs:

Set up push messaging

void setPushIdentifier(final String registrationID)

MobileCore.setPushIdentifier(registrationID);

+ (void) setPushIdentifier: (nullable NSData*) deviceToken;

- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  // Set the deviceToken that the APNS has assigned to the device
  [ACPCore setPushIdentifier:deviceToken];
  //...
}

ACPCore.setPushIdentifier(deviceToken)

@objc(setPushIdentifier:)
public static func setPushIdentifier(_ deviceToken: Data?)

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
            let tokenParts = deviceToken.map { data in String(format: "%02.2hhx", data) }
            let token = tokenParts.joined()
            print("Device Token: (token)")
​
            // Send push token to experience platform
            MobileCore.setPushIdentifier(deviceToken)
        }

Debugging the push messaging set up

If the Mobile Services API is correctly configured, after installing your app on a mobile device, verify that the following SDK debug log is displayed:

To verify, make a request to demdex.net, containing the device push token has been sent:

2019-01-31 18:22:35.261676-0800 DemoApp[935:156015] [AMSDK DEBUG <com.adobe.module.identity>]: Sending request (https://dpm.demdex.net/id?d_rtbd=json&d_ver=2&[email protected]&d_mid=43583282444503123217621782542046274680&d_blob=j8Odv6LonN4r3an7LhD3WZrU1bUpAkFkkiY1ncBR96t2PTI&dcs_region=9)

Set up push tracking

Use the following API to track a push messaging click in Adobe Analytics.

+ (void) collectLaunchInfo:(NSDictionary *)userInfo;

- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    // only send the hit if the app is not active
    if (application.applicationState != UIApplicationStateActive) {
        [ACPCore collectLaunchInfo:userInfo];
    }
    completionHandler(UIBackgroundFetchResultNoData);
}

(void) collectLaunchInfo: (nonnull NSDictionary*) userInfo;

AEPCore.collectLaunchInfo(userInfo)

Troubleshooting push messaging

For more information, see the following:

• ​Android troubleshooting guide​

• ​iOS troubleshooting guide​

Set up in-app messaging

This feature allows you to deliver in-app messages that are triggered from any analytics data or event. After the implementation, messages are dynamically delivered to the app and do not require a code update. In-app messages are created in Mobile Services. For more information, see the create an in-app message tutorial.

To set up your app for in-app messages, implement the following instructions. You can complete these steps even if you have not yet defined any messages in Mobile Services. After you define messages, they are delivered dynamically to your app and displayed without an app store update.

<activity
    android:name="com.adobe.marketing.mobile.MessageFullScreenActivity"
    android:windowSoftInputMode="adjustUnspecified|stateHidden" >
</activity>
<receiver android:name="com.adobe.marketing.mobile.MessageNotificationHandler" />

<activity
android:name="com.adobe.marketing.mobile.MessageFullScreenActivity"
android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen"
android:windowSoftInputMode="adjustUnspecified|stateHidden" >
</activity>
<receiver android:name="com.adobe.marketing.mobile.MessageNotificationHandler" />

Fallback images

When creating a full-screen message, you can optionally specify a fallback image. If your message cannot retrieve its intended image from the web, the SDK attempts to load the image with the same name from your application’s assets folder. This allows you to show your message in its original form, even if the user is offline or the predetermined image is unreachable.

Configuring notification icons

The following methods allow you to configure the small and large icons that appear in the notification area, and the large icon that is displayed when notifications appear in the notification drawer.

public static void setSmallIconResourceId(final int resourceId);

MobileCore.setSmallIconResourceID(R.drawable.appIcon);

public static void setLargeIconResourceId(final int resourceId);

MobileCore.setLargeIconResourceId(R.drawable.appIcon);

Tracking in-app messages

The SDK automatically tracks metrics for your in-app messages.

For full screen and alert style in-app messages, the following metrics are tracked:

• Impressions: when user triggers an in-app message.

• Click throughs: when user clicks the Click through button.

• Cancels: when user clicks the Cancel button.

For custom full screen in-app messages, the HTML content in the message needs to include the correct code to notify the SDK tracking about the following buttons:

• Click-through (redirect) example tracking: adbinapp://confirm/?url=http://www.yoursite.com

• Cancel (close) example tracking: adbinapp://cancel

For local (remote) notifications, the following metrics are tracked:

• Impressions: when user triggers the notification.

• Opens: when user opens app from the notification.

The following example shows you how to include open tracking:

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
​
  // handle local notification click-throughs for iOS 10 and older
  NSDictionary *localNotificationDictionary = launchOptions[UIApplicationLaunchOptionsLocalNotificationKey];
  if ([localNotificationDictionary isKindOfClass:[NSDictionary class]]) {
       [ACPCore collectLaunchInfo:localNotificationDictionary];
  }
​
}
- (void) application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
   [ACPCore collectLaunchInfo:notification.userInfo];
}

Troubleshooting in-app messaging

For more information, see the following:

• ​Android Troubleshooting guide​

• ​iOS Troubleshooting guide​

Acquisition and marketing links

Acquisition and marketing links must be created in Adobe Mobile Services. For more information, see the documentation on Acquisition within the Mobile Services.

When the user downloads and runs an app as the result of a Google Play store acquisition, the data from the referrer is collected and sent to Adobe Mobile Services. Custom keys that were part of the acquisition data from Google Play are name-spaced with a.acquisition.custom.

Using the BroadcastReceiver

1. Implement the BroadcastReceiver for the referrer.

   package com.your.package.name;  // replace with your app package name
   ​
   import android.content.BroadcastReceiver;
   import android.content.Context;
   import android.content.Intent;
   ​
   public class GPBroadcastReceiver extends BroadcastReceiver {
     @Override
     public void onReceive(Context c, Intent i) {
         com.adobe.marketing.mobile.MobileServices.processReferrer(c, i);
     }
   }

2. Update the AndroidManifest.xml to enable the BroadcastReceiver you previously created.

   <receiver android:name="com.your.package.name.GPBroadcastReceiver" android:exported="true">
       <intent-filter>
           <action android:name="com.android.vending.INSTALL_REFERRER" />
       </intent-filter>
   </receiver>

Using the Google Play Install Referrer APIs

Starting on March 1, 2020, Google is deprecating the install_referrer intent broadcast mechanism. For more information, see the Still Using InstallBroadcast? Switch to the Play Referrer API by March 1, 2020 . To continue collecting install referrer information from the Google Play store, update your application to use the Mobile Services extension version 1.1.0 or newer.

With the deprecation, instead of creating a BroadcastReceiver, you need to collect the install referrer URL from a new Google API and pass the resulting URL to the SDK.

1. Add the Google Play Install Referrer package to your gradle file's dependencies:

   implementation 'com.android.installreferrer:installreferrer:1.1'

2. To retrieve the referrer URL from the Install Referrer API, complete the steps in the get the install referrer tutorial.

3. Pass the referrer URL to the SDK:

   MobileServices.processGooglePlayInstallReferrerUrl(referrerUrl);

   To decide the best way to use the Google Play Install Referrer APIs in your app, see Google's documentation. Here is an example of how to use the Adobe SDK with the Google Play Install Referrer APIs:

   void handleGooglePlayReferrer() {
       // Google recommends only calling this API the first time you need it:
       // https://developer.android.com/google/play/installreferrer/library#install-referrer
   ​
       // Store a boolean in SharedPreferences to ensure we only call it once.
       final SharedPreferences prefs = getSharedPreferences("acquisition", 0);
       if (prefs != null) {
           if (prefs.getBoolean("referrerHasBeenProcessed", false)) {
               return;
           }
       }
   ​
       final InstallReferrerClient referrerClient = InstallReferrerClient.newBuilder(getApplicationContext()).build();
       referrerClient.startConnection(new InstallReferrerStateListener() {
           private boolean complete = false;
   ​
           @Override
           public void onInstallReferrerSetupFinished(int responseCode) {
               switch (responseCode) {
                   case InstallReferrerClient.InstallReferrerResponse.OK:
                       // connection is established
                       complete();
                       try {
                           final ReferrerDetails details = referrerClient.getInstallReferrer();                        
   ​
                           // pass the install referrer url to the SDK
                           MobileServices.processGooglePlayInstallReferrerUrl(details.getInstallReferrer());
   ​
                       } catch (final RemoteException ex) {
                           Log.w("Acquisition - RemoteException while retrieving referrer information (%s)", ex.getLocalizedMessage() == null ? "unknown" : ex.getLocalizedMessage());
                       } finally {
                           referrerClient.endConnection();
                       }
                       break;
                   case InstallReferrerClient.InstallReferrerResponse.FEATURE_NOT_SUPPORTED:
                   case InstallReferrerClient.InstallReferrerResponse.SERVICE_UNAVAILABLE:
                   default:
                       // API not available in the Play Store app - nothing to do here
                       complete();
                       referrerClient.endConnection();
                       break;
               }
           }
   ​
           @Override
           public void onInstallReferrerServiceDisconnected() {
               if (!complete) {
                   // something went wrong trying to get a connection, try again
                   referrerClient.startConnection(this);
               }
           }
   ​
           void complete() {
               complete = true;
               SharedPreferences.Editor editor = getSharedPreferences("acquisition", 0).edit();
               editor.putBoolean("referrerHasBeenProcessed", true);
               editor.apply();
           }
       });
   }

Deep link tracking

The SDK can parse key-value pairs of data that are appended to any deep or universal link, provided the link contains a key a.deeplink.id and a corresponding non-null and user generated value. All key-value pairs of data that are appended to the URL string are parsed, attached to a lifecycle hit as context data, and sent to Adobe Analytics.

You can also append one or more of the following reserved keys, with user-generated values, to the deep or universal link:

• a.launch.campaign.trackingcode

• a.launch.campaign.source

• a.launch.campaign.medium

• a.launch.campaign.medium

• a.launch.campaign.content

public static void trackAdobeDeepLink(final Uri uri)

MobileServices.trackAdobeDeepLink

+ (void) trackAdobeDeepLink: (NSURL* _Nonnull) deeplink;

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
    [ACPMobileServices trackAdobeDeepLink:url]
    /*
     Handle deep link
     */
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options {
    [ACPMobileServices trackAdobeDeepLink:url];
    /*
     Handle deep link
     */
    return YES;
}

+ (void) trackAdobeDeepLink: (NSURL* _Nonnull) deeplink;

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
    [AEPMobileServices trackAdobeDeepLink:url];
    /*
     Handle deep link
     */
    return YES;
}

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<NSString *, id> *)options {
[AEPMobileServices trackAdobeDeepLink:url];
    /*
     Handle deep link
     */
    return YES;
}

Integration with Apple Search Ads (iOS)

The Adobe Experience Platform SDK leverages Apple's Search Ads attribution to attribute app downloads that originate from Search Ads campaigns in the Apple App Store. For more information about Search Ad campaigns, see Apple Search Ads. This optional feature helps you easily measure the effectiveness of your Search Ads app download campaigns by adding a few lines of code to your app.

Implement Search Ads integration

To enable your app for Search Ad attribution, you will need to add the iAd framework, in addition to the Mobile Services extension to your app.

Reporting on Search Ads Attribution

Apple Search Ads attribution data is provided in the acquisition name, the source, and the term values.

If attribution = true , all of the iad-* fields will be included in a Lifecycle request to Adobe Analytics. In addition, the following values will be mapped from the "iad" dictionary to our typical acquisition context data fields:

• iad-campaign-id --> a.referrer.campaign.trackingcode

• iad-campaign-name --> a.referrer.campaign.name

• iad-adgroup-id --> a.referrer.campaign.content

• iad-keyword --> a.referrer.campaign.term

This mapping ensures that the values are available in Adobe Analytics standard reporting.

Migration notes

To prepare for your migration, please note the following information:

• Lifetime value is not supported on the Experience Platform SDK, so it should not be used to trigger in-app messages or local notifications.

• ce is no longer supported as a trigger for in-app messages or local notifications.

• a.internalaction or action (from Lifecycle) can be used to trigger in-app messages or local notifications. You should, however, use LaunchEvent instead.

• Local notifications do not support Android 8.0 or higher.

Configuration keys

Watch the video

Additional information

• Visit Mobile Services documentation​

• Visit Mobile Services​