Android SDK implementation guide

This implementation guide provides steps for integrating the Oracle Maxymiser Mobile Application Testing solution 'MMTApp' into native Android apps. It also describes how to create A/B test campaigns. This guide assumes that you are familiar with creating apps for Android.

Download the appropriate SDK package for your platform and region here.

Getting started

You will require an Oracle Maxymiser User Interface login to access the test management and reporting interface. If you have not received login credentials as part of the on-boarding process, please contact Oracle Maxymiser. We are more than happy to send relevant authorization credentials to access the Oracle Maxymiser UI.

Prerequisites for using and integrating the API with an app:

• A development environment with Android SDK installed.
• A proficiency in development using Java for Android.

Feature support by Android version:

Integration guide

To integrate the SDK please follow these.

You should be prepared to build 2 versions of your app; one with sandbox enabled and one for production. Doing this is advantageous as the setSandbox and printElementIds calls are not explicitly defined in the initialization steps and are vital when doing app testing.

Locate and extract the MMTApp library zip file, which is distributed alongside this documentation Launch IDE, and open the project with Android application to be tested.

Add the MMTApp.jar to the classpath of your app:

• Instruction for Eclipse
• Instruction for Android Studio

SDK requires the following permissions to be added to the AndroidManifest.xml:

<uses-permissionandroid:name="android.permission.INTERNET" />

<uses-permissionandroid:name="android.permission.ACCESS_NETWORK_STATE" />

Tests for native apps can be created in three ways:

• Using Oracle Maxymiser's standard web testing method which uses a JavaScript tag: You can use this to test mobile web pages or HTML inside an app container (hybrid app).
• Using the 'No App Store' approach which uses the Oracle Maxymiser SDK: You can use the SDK to inject campaign content directly into your app without having to make any changes to your app's source code or release an update through the App Store (available for iOS apps built using the Apple UIKit and Android apps build using Android UI kit elements).
• Using the 'Manual' approach: This approach works for both iOS and Android apps and uses Oracle Maxymiser as a decision and reporting engine. You need to do some development work on the source code of your app, and release updates to your users, however you need to create more complex test variants. The Oracle Maxymiser SDK provides the decision engine and feeds the results back to our reporting systems.

Follow the instructions below to Initialize the SDK depending on the method you wish to use.

No Store Update approach

No Store Update approach is a way to build A/B tests for native applications whereby variants of the user experience are injected into the app remotely. This approach allows campaigns and updates of variants to be published from Oracle Maxymiser rather than code changes within the app followed by a release cycle. In contrast, the Manual approach uses variants that are coded into the app and released to users through a general release. In this case. Oracle Maxymiser is used as a decision and reporting engine.

Important: The No Store Update approach is supported only for API16 onwards. On API15 and earlier, the SDK will not apply variant transformations or track actions.

Initialize SDK

During initialization of your application, use the following code to initialize SDK:

// Show Interstitial page
MMTApp.startWithOptions(application,
    MMTApp.Options.optionsForSite("myapp")
        .setRequestTimeout((3000)),
    new MMTApp.Handler() {
        @Override
        public void onStarted() {
        // Hide interstitial page and display Home page
        }
    });

Replace "myapp" with the name of your Site in the Oracle Maxymiser UI.

Options allows you to set initialization parameters such as timeout and the Oracle Maxymiser environment to use.

Important: Please display your application's home page in initialized handler. You cannot run campaigns on pages that are shown before the SDK is initialized.

Create campaign

You are now ready to create campaigns. See our page App Testing From Site Creation to Live Publish for information.

Manual approach

Initialize SDK

During initialization of your application, use the following code to initialize SDK:

MMTApi api = MMTApp.getApi(context, "myapp");
api.setSandbox(true);

Replace "myapp" with the name of your Site in the Oracle Maxymiser UI.

Later, you can refer to the first created API by MMTApp.getDefaultApi(), so there is no need to keep the reference to the created API.

Please note you don't have to initialize API if you initialized SDK with No Store Update approach.

Create campaign

You are now ready to create campaigns. See our page App testing for information.

Fetch experiences

The code below will fetch and cache all campaigns and their variants for later use.

// Show interstitial page

The first argument is a handler that we invoke once experiences are fetched. It is safe to update UI inside this handler as it will be invoked on the main thread.

Please be aware that due to latency there may be a short delay in receiving a response from Oracle Maxymiser with details of the variants to display. Therefore, we recommend fetching experiences in a place in your app where a user may naturally experience a delay, for example an interstitial page or a search term/login input page. We recommend fetching experiences at the app launch.

Content transformations

When experiences are fetched, you can use them to transform content.

There are two methods you can choose from to implement content transformations.

Variant name

Base the decision logic of your application on the variant name. In this case, Variants of the user experience for the View element use the format shown in the following example.

(vois)viewWillAppear:(BOOL)animated {
[super viewWillAppear: animated;
UIColor *color = nil;
NSString *variantName = [[[MMTApp defaultApi] getExperiences]
[getVariantNameForCampaign:@"Campaign" element:@"view"];
if ([@"Variant1"isEqualToString:variantName]) {
color = [UIColorgreenColor ];
}else if ([@"Variant2"isEqualToString:variantName]) {
color = [UIColorblueColor ];
}else{ 
}
self.view.backgroundColor= color; 
[MMTApp defaultApi] trackContentSeen:@"Campaign"];
}

Important: Make sure that experiences are applied each time the UI is presented to the user as experiences may change as a result of tests stopping or personalization logic.

Environments

The Oracle Maxymiser UI supports two environments: Sandbox and Production.

Sandbox

Sandbox is a development test environment where campaigns are created and configured. All testing on your application should be carried out in Sandbox. All sandbox traffic is served from pre-defined Company IPs and is not retained for reporting or analysis purposes.

Remember to add your device IP to the Company IP list for your Site (under Site Administration options in the Oracle Maxymiser UI) prior to testing the campaign in Sandbox mode.

To preview a specific Variant in-app for Quality Control (QC) testing purposes:

1. Use the Oracle Maxymiser UI - Campaign Settings > Campaign Content > Elements & Variants page to set weightings of all variants to '0'.
2. Set the weight of the variant that you want to preview to '100'. Run your application and make sure that the transformation is applied correctly and that all other functions are working as expected.
3. Repeat these steps for all variants in the user experience.
4. Complete the necessary stages to trigger all configured actions.
5. Check the Action Log report to ensure that the action's value and attributes are logged correctly.

Note: Data captured in Sandbox mode does not appear in the Oracle Maxymiser analytics reports. This mode exists for QC testing purposes only. Apps must not be released to users with tests connected to a Sandbox environment because Service Level Agreements (SLAs) are not supported and reporting will not be available.

Production

Production is the environment used to serve production (live user) traffic.

Data gathered from this environment is available in the reporting area (see Oracle Maxymiser UI - Analytics tab) for analysis to determine which variant is the best performer.

MMTApp allows the environment to be toggled as follows.

No Store Update Approach:

// Show interstitial page 
[MMTAppstartForSite: @"myapp"
    options: @{
    MMTAppOptionUseSandbox : @YES
        }
    handler: ^{
//Hide interstitial page and display Home page
}];

Manual Approach:

#ifdef DEBUG
[api useSandbox:YES];
#endif

Important: Never release an app to end users containing a campaign connected to the Sandbox environment.

API reference

MMT app

Class Overview

Provides facilities to create API for a Site and contains methods for SDK configuration.

Public Methods

public static MMTApi getDefaultApi()

Returns default MMTApi object set explicitly with setDefaultApi(api) or first API object created with getApi

(context,site), returns null if default API is not available.

public static void setDefaultApi(MMTApi api)

Sets default API.

public static MMTApi getApi(Context context, String site)

Creates new API for the given Site.

public static void setUserAttribute(Context context, String name, String value)

Sets user attribute. Please ensure that a custom attribute with this name exists.

public static void setUserAttributeDynamic(Context context, String name, MMTApp.AttributeValueResolver resolver)

Sets dynamic user attribute. Please ensure that a custom attribute with this name exists.

public static void setUserId(Context context, String id)

Sets user ID.

public static void startWithOptions(Application application, MMTApp.Options options, MMTApp.Handler handler)

Starts SDK in No Store Update approach mode.

public static void stop()

Turns off SDK in No Store Update approach. Manual approach will remain operational.

public static void applyOnActivity(Activity activity)

Forces UI transformations on an activity. Should be used to apply experiences on activities that change their views layout dynamically. i.e. on Fragment change.

public static void setViewId(View view, String id)

Sets view ID.

public static void setLogger(Logger logger)

Sets logger to be used by SDK.

public static void setLogLevel(Logger.LogLevel level)

Sets logging level.

public static void setPrintElementsIDs(boolean printIDs)

Enables or disables element IDs output.

MMTApp.AttributeValueResolver

Interface Overview

Interface definition for a callback to be invoked to provide an attribute value.

Public Methods

String getAttributeValue()

Returns attribute value.

MMTApp.Handler

Interface Overview

Interface definition for a callback to be invoked when SDK has been started in No Store Update approach mode.

Public Methods

void onStarted()

Callback method to be invoked when SDK has been started in No Store Update approach mode.

MMTApp.Options

Class Overview

Class that holds SDK start options for No Store Update approach.

Public Methods

public MMTApp.Options setGenerationsPage(String generationsPage)

Sets Page to be used to fetch experiences from. By default, Generations page is used.

public MMTApp.Options setActionsPage(String actionsPage)

Sets Page to be used for action tracking. By default, Actions page will be used.

public MMTApp.Options setSandbox(boolean sandbox)

Specifies whether Sandbox configuration should be used. By default, Production configuration will be used.

public MMTApp.Options setWiFiOnly(boolean wifiOnly)

Specifies whether new experiences can be fetched only when user is connected to a Wi-Fi network. By default, any available network will be used.

public MMTApp.Options setRequestTimeout(int requestTimeout)

Sets the maximum time in milliseconds which can be spent making a request to our servers. Default is 3 seconds. When the time is exceeded, the attempt to fetch experiences will cease and the previous user experience will be selected.

MMTApi

Interface Overview

Interface to be used to fetch experiences and track actions.

Public Methods

void setSandbox(boolean sandbox)

Specifies whether Sandbox configuration should be used. By default, Production configuration will be used.

void setWiFiOnly(boolean wifiOnly)

Specifies whether new experiences can be fetched only when user is connected to a Wi-Fi network. By default, any available network will be used.

void setRequestTimeout(int requestTimeout)

Sets the maximum time in milliseconds which can be spent making a request to our servers. Default is 3 seconds.

When the time is exceeded, the attempt to fetch experiences will cease and the previous user experience will be selected.

void fetchExperiences(MMTApi.FetchExperiencesHandler handler)

Fetches new experiences from Oracle Maxymiser platform for a default Page named 'Generations'. Fetching will be performed on a background thread.

void fetchExperiences(MMTApi.FetchExperiencesHandler handler, String page)

Fetches new experiences from Oracle Maxymiser platform for a specified Page. Fetching will be performed on a background thread.

Experiences getExperiences()

Returns fetched experiences that should be used for content transformations. Returns null if experiences were not fetched.

void trackContentSeen(String campaign)

Tracks a special type of action for confirmation that a user has been served the content.

void trackAction(String action, int value, String attribute)

Tracks a user action for a default Page named 'Actions'. Value can be used for the tracking of various parameters such as amount and sum and attribute for the tracking of various additional information related with the action.

void trackAction(String action, int value, String attribute, String page)

Tracks a user action for a specified Page. value can be used for the tracking of various parameters such as amount and sum and attribute for the tracking of various additional information related with the action.

MMTApi.FetchExperiencesHandler

Interface Overview

Interface definition for a callback to be invoked when SDK has fetched new experiences.

Public Methods

void onExperiencesFetched()

Callback method to be invoked when SDK has fetched new experiences.

Experiences

Interface Overview

Interface to be used to retrieve generated variants for the fetched experiences.

Public methods

String getVariantName(String campaign, String element)

Retrieves a generated variant name for a campaign and the element which is related to a test configuration in the Oracle Maxymiser UI.

Returns the name of the generated variant for the element in the campaign.

Returns null for the following cases: the campaign is not started, the campaign is finished, the campaign is paused or the site is disabled. In any of these situations a process to render default content should be put in place.

Logger

Interface Overview

Interface to be used for logging messages from the SDK. Implementation of this interface can be provided to the MMTApp class.

Public Methods

void debug(String tag, String message)

Logs message with log level Debug.

void info(String tag, String message)

Logs message with log level Info.

void warn(String tag, String message)

Logs message with log level Warning.

void warn(String tag, String message, Throwable e);

Logs message with log level Warning.

void error(String tag, String message)

Logs message with log level Error.

void error(String tag, String message, Throwable e)

Logs message with log level Error.

void print(String tag, String message)

Prints technical information upon user request, even when the logger is off.

System limitations

The Oracle Maxymiser Mobile Library currently has the following system limitations:

1. Each app can connect to one Oracle Maxymiser site entity.
2. The user interface contains some web-specific terminology. The guide above covers the settings that are supported. All others in the Oracle Maxymiser UI can be disregarded. If in doubt, Oracle Maxymiser can assist with the campaign QC processes.
3. MaxPredict and Recommend are not supported.
4. A reduced number of user attributes are available for mobile app campaigns. See Appendix 2 for a list of supported attributes.
5. Filter Action by Referrer URL and Filter Action by URL parameter are not supported within mobile app testing.