Building a SAS CI-enabled mobile app for Android

[#1]

Today I'll describe how to create a CI-enabled mobile app for the Android platform.  For the sake of brevity we'll assume you've already downloaded the multiplatform SDK bundle, and created the following items in the CI 360 Design Center:

1. CI360ReferenceOne Mobile Application
   • Application ID 'CI360ReferenceOne'
2. CI360ReferenceOneOpen Mobile Event
   • Event ID 'CI360ReferenceOneOpen'
3. CI360ReferenceOneWelcome HTML Creative
4. CI360ReferenceOneWelcomeBack HTML Creative
   • The content should be easily distinguishable from CI360ReferenceOneWelcome; mine has different text and a different background color.
5. CI360ReferenceOneSpot Mobile Spot
   • Associated to the CI360ReferenceOne Application
   • Spot ID 'CI360ReferenceOneSpot'
   • Default content CI360ReferenceOneWelcome Creative
6. CI360ReferenceOneWelcomeBackTask Mobile Spot Task
   • Associated Spot CI360ReferenceOneSpot
   • Content CI360ReferenceOneWelcomeBack Creative
   • Targeting Event CI360ReferenceOneOpen 'at least 3 times in the past week'

See the User's Guide for SAS Customer Intelligence 360 for the details on how to create these items.

We will be building this app with Android Studio 2.2 on Mac OS Sierra and running the app on a Nexus 5X with Android 7.1.2.  The process should be similar on any supported platform.  We'll start by going through the new project wizard:

We'll target phones and tablets at Android 4.1+

Start with a simple empty Activity

And keep the defaults for the Activity details

Once the project is initialized and Android Studio has settled, it's a good idea to run the app once to ensure we've got a good baseline.  If something goes wrong here, there's something wrong with the basic Android development environment.

Now that we know the app works on its own, let's bring in the SDK.

First add a Gradle dependency for the Gson library that the SDK will use for object (de)serialization.  Add this to your 'app' level build.gradle file.  Ensure your project includes a compile fileTree dependencies on the 'libs' directory as well (it should be there already).

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    androidTestCompile('com.android.support.test.espresso:espresso-core:2.2.2', {
        exclude group: 'com.android.support', module: 'support-annotations'
    })
    compile 'com.android.support:appcompat-v7:24.2.1'
    compile 'com.google.code.gson:gson:2.2.4'
    testCompile 'junit:junit:4.12'
}

Copy the SASCollector.jar and SASCollector.properties file from the android folder of the multi-platform SDK bundle to the app/libs and app/src/main/assets directories respectively.  You may have to create the assets directory.

After adding the library, you may need to manually refresh the Gradle project for the SDK classes to become available to the IDE

At a minimum, the SDK will need INTERNET permissions given to the app, in order to communicate to the CI360 backend services.  Your app will likely need the same permission, go ahead an add it to your app's manifest file.

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

The simplest way to activate the CI360 SDK for Android is to use the provided MonitoredApplication class as your app's base Application class.  This can be done the in the app's manifest file as well:

<application
    android:name="com.sas.mkt.mobile.sdk.MonitoredApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:supportsRtl="true"
    android:theme="@style/AppTheme">
    <activity android:name=".MainActivity">
        <intent-filter>
            <action android:name="android.intent.action.MAIN" />

            <category android:name="android.intent.category.LAUNCHER" />
        </intent-filter>
    </activity>
</application>

You can also create your own Application class that extends the SDK's MonitoredApplication class and reference it here.  Just be sure to call super functions for anything you override in your class.

Install and run the app again to establish a good baseline.  The app should look the same as it did before, and you should see no errors from the SDK in the device's logcat output.

The app is now instrumented with basic focus/defocus tracking, but let's add something we can see.  Open your MainActivity's layout file in res/layout/activity_main.xml and replace the 'Hello World' label with a SASCollectorAd View:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/activity_main"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:paddingBottom="@dimen/activity_vertical_margin"
    android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    tools:context="com.example.ci360referenceone.MainActivity">

    <com.sas.mkt.mobile.sdk.ads.SASCollectorAd
        android:id="@+id/CI360ReferenceSpot"
        android:layout_width="match_parent"
        android:layout_height="250dp"></com.sas.mkt.mobile.sdk.ads.SASCollectorAd>

</RelativeLayout>

Now instruct your MainActivity to load the view with content each time the Activity is resumed (when exactly the content is refreshed is up to you, choose what best fits your app's UX)

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    }

    @Override
    protected void onResume() {
        super.onResume();

        SASCollectorAd ad = (SASCollectorAd)findViewById(R.id.CI360ReferenceSpot);
        
        ad.load("CI360ReferenceOneSpot", null);
    }
}

The ID of the View is not important here, but the String passed to the load(...) API must match the ID used you created the Mobile Spot in the CI360 Design Center. The second parameter is a set of optional attributes we're not using in the case, so we can just pass null.

Run the app and you should now see your CI360ReferenceOneWelcome content rendered.

Now let's make the content more dynamic.  Each time the MainActivity is created, we'll fire the CI360ReferenceOneOpen event to CI360 backend.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    SASCollector.getInstance().addAppEvent("CI360ReferenceOneOpen", null);
}

Here again, the String passed the API must match the Event ID used when the Mobile Event was created in the CI360 Design Center.  The second parameter is again a set of attributes we're not using in this case. 

Run the app once again; you should initially see the same content.  Close and re-open the app twice more and the content should change to the CI360ReferenceOneWelcomeBack content.

To recap:

• The app loads the CI360ReferenceOneSpot into a SASCollectorAd View in the MainActivity.  By default this spot loads the CI360ReferenceOneWelcome Creative.
• Each time the app's MainActivity is created (each time the app is opened) it emits the CI360ReferenceOneOpen event to the CI 360 backend
• The CI360ReferenceOneWelcomeBackTask targets devices that have emitted the CI360ReferenceOneOpen event at least 3 times in the last week and provides alternative content to the CI360ReferenceOneSpot in the form of the CI360ReferenceOneWelcomeBack Creative.