Appia SDK - Android 2014.31

Our documentation has moved. Please click here for the most up to date documents.

Table of Contents

2014.31 Release Notes

  • OpenUDID, MacAddress, Handset ID (IMEI), and AndroidID have been removed in favor of Android's Advertising Identifier.
    • As a result, the OpenUDID opt-out configuration is now obsolete
  • All Appia SDK logging has been prefixed with the text appia.

Quick Start

Requirements

  1. Android OS version 2.2 or higher

  2. AppiaSDK.jar 
    1. Downloaded from here (~130kb) 
    2. Added to your libs folder
    3. Added to your project's build path
  3. A unique identifier (siteId) for your app/site, provided by Appia
  4. Implement Google Play Services SDK

Initialization

  1. Ensure the following permissions are set in your AndroidManifest.xml under the <manifest> tag

    <uses-permission android:name="android.permission.INTERNET"/> 
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/> 
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/> 
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> 
  2. Add the following (2) activity, (1) service elements, and (1) meta-data elements in your AndroidManifest.xml under the <application> tag.  Of particular importance is the meta-data element; if it is not added then using the Appia SDK may result in an application crash.  Adding this tag means that Google Play Services have been referenced in your project (please refer to Google's documentation for more information on how this may be done).

    <activity
    	android:name="com.appia.sdk.DisplayAppWallActivity"
        android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
        android:theme="@android:style/Theme.Dialog" >
    </activity>
    <activity
    	android:name="com.appia.sdk.DisplayBannerActivity"
        android:configChanges="keyboard|keyboardHidden|orientation|screenSize"
        android:theme="@android:style/Theme.Dialog" >
    </activity>
    <service 
        android:name="com.appia.sdk.AppiaReferrerService"
        android:process=":com.appia.sdk.AppiaReferrerServiceProcess">
    </service>
    <meta-data 
    	android:name="com.google.android.gms.version"
        android:value="@integer/google_play_services_version">
    </meta-data>
  3. Initialize the SDK for use:  

    Appia appia = Appia.getAppia(this);
  4. Set your site ID: 

    appia.setSiteId(1234);

    where the site id parameter is an int value, provided to you by Appia.

  5. Start your session at the end of your initialization: 

    appia.startSession();

Ad Display for Publishers

There are two type of ads supported by the Appia SDK:

AppWall

  • Displays a list of ads in a full-screen pop-up/interstitial or embedded within a view.
  • Look and feel is fully customizable for your best in-app experience. *Please contact your Appia representative to have your skin quickly created.

Display Ads

  • Displays a single ad image as a pop-up/interstitial or embedded banner within a view

App Wall Integration

To display the App Wall: 

Option 1 - Full-screen or popup interstitial:  Using an Appia-provided activity:

appia.displayWall(this, WallDisplayType.POPUP);		//Or, WallDisplayType.FULL_SCREEN

where "this" is an Activity or Context and the second parameter sets the App Wall display type.

Option 2 - Within your app's navigation:  Embedding the App Wall in your own activity:

WallResult wr = appia.getWall(this);
if (wr.hasError())
{
	TextView textView = new TextView(this);
	textView.setGravity(Gravity.CENTER);
	textView.setText("Unable to display more applications.");
	myParentView.addView(textView);			//Display message to end-user
}
else
	myParentView.addView(wr.getView());		//Show the App Wall

where getWall() is executed whenever the App Wall should be displayed and "this" is a reference to the activity. For example, if the App Wall is embedded within a tabbed view, getWall() should be called whenever the tab containing the App Wall is selected. The hasError() check is used to test for problems that may have occurred during App Wall view assembly.  If true, a substitute view should be used since the App Wall view will not be valid.

Integrating with Activity State

Be aware that Android's default behavior upon screen rotation is to recreate the activity - this means the App Wall view will be recreated (and then reloaded) as well.  Adding "orientation" (and additionally "screenSize", when targetting API 13 or higher) to the configChanges attribute of your activity in the AndroidManifest can alleviate this, but may have other implications in your application programming (see Android documentation: Handling Runtime Changes).

Hardware Acceleration

By default, hardware acceleration is enabled to ensure smooth scrolling of the App Wall. Hardware acceleration was introduced as an option in Android 3.0 (API level 11).  Note that hardware acceleration can be configured outside of the Appia SDK by the application developer (this would normally be done in the AndroidManifest.xml).  If hardware acceleration is enabled outside of the Appia SDK, the appia.setHardwareAcceleratedWall method will not override this configuration.  If you would like to disable hardware acceleration:

appia.setHardwareAcceleratedWall(false)

Interstitial Ad Integration

  1. To display an interstitial ad: 

    Pop-up/interstitial:  Using an Appia-provided activity:

    appia.displayInterstitial(this, adParameters, BannerAdSize.SIZE_300x250);

    where "this" is an Activity or Context and "300x250" is the requested size to display. adParameters is an optional (may be null) AdParameters object into which custom parameters may be stored for sending with the ad request (see "Custom Ad Parameters" section below).

Banner Ad Integration

Within your app's natigation:  Embedding the banner ad in your own activity:

 

BannerAdResult adResult = appia.getBannerAd(this, adParameters, BannerAdSize.SIZE_320x50);
if (adResult.hasError())
{
	TextView textView = new TextView(this);
	textView.setGravity(Gravity.CENTER);
	textView.setText("Unable to display more applications.");
	myParentView.addView(textView);			//Display message to end-user
}
else
	myParentView.addView(adResult.getView());		//Show the banner ad

 

Integrating with Activity State

The SDK will need to be informed when an embedded ad is displayed or hidden. To accommodate this, please modify your Activity/Fragment lifecycle callbacks as follows to invoke "willAppear" or "didDisappear" (or invoke them when you know that an embedded ad is being made visible or hidden in any other way.)

@Override
public void onResume() {
	super.onResume()
	if (adResult != null)
		adResult.willAppear(); // adResult is a reference to an earlier BannerAdResult
}
 
@Override
public void onDestroy() {
	super.onDestroy();
	if (adResult != null)
		adResult.didDisappear();
}

 

Ad Sizes

Call the ad size that best fits the device, orientation, and desired user-experience. 

If the interstitial is larger than the device's screen size, the image will be scaled down to fit the screen.

 

Landscape

300x50

320x50

300x250

480x320

1024x768

 

Portrait

320x480

768x1024

Custom Ad Parameters

App wall and banner ads support passing custom ad parameters through an AdParameters object.. To pass custom parameters, first create an AdParameters object.

AdParameters adParameters = new AdParameters();

The AdParameters object has two HashMap objects – adParameters.appiaParameters and adParameters.userParameters – into which parameter values can be stored, e.g.:

adParameters.getAppiaParameters().put("appiaParam1", "param1Value");
adParameters.getUserParameters().put("customParamA", "custom-param-value");

These values will be passed along with ad requests that use the AdParameters object, e.g.:

appia.displayWall(this, adParameters, WallDisplayType.POPUP);
or
appia.displayInterstitial(this, adParameters, BannerAd.SIZE_480x320);

If you do not wish to use custom parameters, you may omit the parameter (where supported), or pass in a null object for ad calls, e.g.:

appia.displayWall(this, null, WallDisplayType.POPUP);

Conversion and User Quality Tracking 

For app developers advertising through Appia, there are several types of tracking supported by the Appia SDK

  1. Install Tracking
    1. When an install of the app is generated from an Appia ad, the SDK will pass the Appia click ID (referrer) to the Appia API
  2. Loyal User Tracking
    1. For analysis of user quality, Appia encourages app developers to integrate with Appia's loyal user API, which will record the number of app opens per user
    2. The first time the application is launched, the SDK will notify the Appia API of a "first-time open." If the user reinstalls the application or clears the application data, the next application launch will register a "first open" again.
  3. Post-Install Event Tracking
    1. The SDK allows for recording custom events that occur after the app has been installed.  Posting these events helps Appia calculate lifetime value of users, ultimately resulting in the highest bid rates possible for campaigns being run by a publisher.
  4. User Profiles
    1. Using additional information about your users, Appia can intelligently target the ads that you users find the most compelling and increase your publishing revenue.

Install Tracking

With Existing Broadcaster Receiver

  1. Add the following to your existing BroadcastReceiver that handles your installs:

 

AppiaReferrerHandler appiaReferrerHandler = new AppiaReferrerHandler();
appiaReferrerHandler.onReceive(context, intent);

Integration with Google Analytics install tracking

The above AppiaReferrerHandler code supports click IDs (referrer) in their simple form or when included as part of a Google Analytics request URL (the 'utm' fields).  In either of these cases the click ID will be delivered only to Appia for install tracking; for more information on Google Analytics install tracking (as well as on GA request URLs) see Google's Campaign Tracking documentation.

With a New Broadcaster Receiver

  1. Add the following under the <application> tag:

    <receiver android:name="com.appia.sdk.AppiaReferrerHandler" android:exported="true">
    	<intent-filter>
    	    <action android:name="com.android.vending.INSTALL_REFERRER" />
    	</intent-filter>
    </receiver>

Loyal User Tracking

By default, the SDK will track each time the application is opened, where this means that the app is either launched or returns to the foreground. The application’s identifier and the advertisingIdentifer (if available) is recorded. 

To disable the tracking of application opens, add the following method before calling startSession: 

 

appia.setShouldTrackOpens(false);

Post-Install Event Tracking

To track a post-install event, call the following method at the appropriate point in your code:

Appia.getAppia().trackEvent("<event>");

where <event> is the name of the event you want to track.  Some events that are currently trackable include:

    • open
    • purchase
    • registration

Note that by default an "open" is tracked in the initialization process.

User Profiles

User Profile Data

Using the Appia SDK, specific elements of user profile information can be collected and sent to Appia.  The elements available to be collected and sent are described in the table below:

ElementDescription
AgeThe user's age in years (e.g. 18)
SexThe user's sex
IncomeThe user's approximate annual income, in US dollars (e.g. 65000)
ChildrenA true/false value identifying if the user has children or, a number of children
Zip CodeThe user's 5 digit US zip code
EducationHighest level of education the user has completed. Options are: "highschool", "incollege", "somecollege", "associate", "bachelors", "masters", "phd", or "professional"
Marital StatusThe user's marital status. Options are: "single", "divorced", "engaged", "relationship"
Political AffiliationThe user's political view or party affiliation. Options are: "republican", "democrat", "conservative", "moderate", "liberal", "independent", or "other"
KeywordsAny additional relevant description of the user or their preferences separated by semi-colons. e.g. "soccer;scores;basketball"

Setting profile data and then sending to Appia

  1. Known element values are set through properties of a "UserData" object in a type-safe manner.  An element value may also be assigned as 'unknown'.  In the following example, known values for five profile elements and one unknown value are set and then sent to Appia:

    UserData userData = new UserData();
     
    userData.getAge().setValue(35);
    userData.getSex().setValue(Sex.MALE);
    userData.getChildren().setValue(true);	//Or: userData.getChildren().setNumberOfChildren(4);
    userData.getEducation().setValue(Education.MASTERS);
    userData.getKeywords().setValue("soccer;scores;basketball");
    userData.getPolicitalAffiliation().setValueUnknown(true);
     
    Appia.getAppia().sendUserData(this, userData);

    where "this" is an Activity or Context.

     

    Element properties expose two methods that may help make value mapping an easier exercise: addMapping and setValueFromString. By predefining the mapping, a string can be used to set the element's value. A sample usage of this follows:

     

    //NonActivity.java
    UserData userData = new UserData();
     
    userData.getMaritalStatus.addMapping("single", MaritalStatus.SINGLE);
    userData.getMaritalStatus.addMapping("divorced", MaritalStatus.DIVORCED);
    userData.getMaritalStatus.addMapping("engaged", MaritalStatus.ENGAGED);
    userData.getMaritalStatus.addMapping("married", MaritalStatus.RELATIONSHIP);
    userData.getMaritalStatus.addMapping("dating", MaritalStatus.RELATIONSHIP);
     
    //Activity.java
    userData.getMaritalStatus.setValueFromString(myForm.getMaritalStatus());
    Appia.getAppia().sendUserData(this, userData);