Setting Up Android SDK

Setting Up the SDK

The purpose of this section is to explain the components of the Koupon Media SDK and to help you configure it for use with an existing Android app. We assume that you have already downloaded the Koupon Media SDK (or our starter Eclipse project if you do not have an existing app), and if applicable, the Gimble SDK.

Add the Koupon Media jar File to your Android Application

  1. Unzip the Koupon Media SDK archive.
  2. Copy kouponsdk.jar from the SDK’s bin folder into your Android project’s Libs folder.
  3. If you are also using the Gimbal SDK, refer to the documentation included in the Gimbal SDK package for instructions on adding requisite jar files.

Configure properties File

In order for your Android app to use the Koupon Media SDK (and, optionally, the Gimbal APIs), it must authenticate using your API key, name, and desired capabilities. To configure the Koupon Media SDK properties file, follow the steps below.

  1. If it doesn’t already exist, create a folder named properties and place it in your Android project’s assets folder (so your path should be /assets/properties).
  2. Create a file named kouponconfiguration.properties and place it in assets/properties.
  3. Open kouponconfiguration.properties and add the following entries:
 
authKey=your_auth_key
authSecret=your_auth_secret
DPCode=APP
domain=http://consumer.kouponmedia.com/v2
appEventDomain=http://appevent.kouponmedia.com/v2
gcmSenderId=your_gcm_sender_id
geofenceEnabled=true

 

Required or Optional Entry Description
Required authKey Your Koupon Media authKey
Required authSecret Your Koupon Media authSecret
Required DPCode This is your channel that will sort offers only available for that channel.
Optional domain Specify if testing on a non-production server
Optional appEventDomain Specify if testing on a non-production server
Optional gcmSenderId Specify for GCM
Optional geofenceEnabled Specify for geofencing

The Koupon Media SDK supports production and non-production environments. During the integration and testing phases of application development, it is necessary to ensure the proper endpoint URL is used for the intended environment. If this value is not set, then the SDK will default to using the production environment.

 

(Optional) Configuring your Properties File for Gimbal

If you are also utilizing the Gimbal SDK, you need to create a second properties file within assets/properties and name it usercontext.properties. Inside this file, you must add the following entries:

 
app.key=your_gimbal_api_key
feature.name=Android Sample
app.capabilities=Geofence

Required or Optional Entry Description
Required app.key Gimbal API key
Required feature.name Describes the feature you are providing for your users.
Required app.capabilities Tells Gimbal that you will be using its geofencing capabilities (this is case-sensitive)

 

By default, when you enable the SDK using enable(), a Gimbal branded dialog containing the end user consent, privacy notice and terms of service will be presented to the end user. However, you have the choice to display your own privacy notice and end user opt-in consent in lieu of the Gimbal branded dialog. Important You will be bound by the “White Label Mode” terms within the Gimbal Developer Agreement.

To use this feature, simply add the property custom.opt.in.flow=true to usercontext.properties file.

Custom opt-in Flow for user privacy

Please refer to the documentation included in the Gimbal SDK package for additional information.

Update the AndroidManifest.xml File

To allow Koupon Media and related push notifications to function in your Android application, you’ll need to add the following elements to your AndroidManifest.xml file (between the <application> </application> tags).

 For the Basic Koupon Media SDK

Add the following permissions to AndroidManifest.xml:

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

 
Add the following service to AndroidManifest.xml:

 
<service android:enabled="true" android:name="com.kouponmedia.kouponsdk.KMLocationService" />

 

For GCM (Push)

In addition to the permissions listed above for the basic Koupon Media SDK, add the following permissions to AndroidManifest.xml for GCM:

 
<permissionandroid:name="COM.PACKAGENAME.permission.C2D_MESSAGE" android:protectionLevel="sign
ature" />
<uses-permission android:name="COM.PACKAGENAME.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<uses-permissionandroid:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />

 
Note: Replace “COM.PACKAGENAME” with your package name.

In addition to the service listed above for the basic Koupon Media SDK, add the following services to AndroidManifest.xml for GCM:

 
<service android:name="com.kouponmedia.kouponsdk.push.KMPushIntentService" />

 
Add the following receivers to AndroidManifest.xml:

 
<receiver android:name="com.kouponmedia.kouponsdk.push.KMPushBroadcastReceiver"
android:permission="com.google.android.c2dm.permission.SEND" >
<intent-filter>
<action android:name="com.google.android.c2dm.intent.RECEIVE" />
<action android:name="com.google.android.c2dm.intent.REGISTRATION" />
<category android:name="COM.PACKAGENAME" />
</intent-filter>
</receiver>

 

Add the following metadata to AndroidManifest.xml:

 
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />

 

For Advanced Push

In addition to the permissions, service, receivers and metadata listed above for GCM (push), add the following activity to AndroidManifest.xml for advanced push:

 
<activity
android:name="com.kouponmedia.kouponsdk.push.KMAdvancedPushActivity"
android:exported="false"
android:parentActivityName="COM.PACKAGENAME.MainActivity" >
<meta-data
android:name="android.support.PARENT_ACTIVITY"
android:value="COM.PACKAGENAME.MainActivity" />
</activity>

 
Note: Replace “COM.PACKAGENAME” with your package name.

(Optional) For the Gimbal SDK

If you are also utilizing the Gimbal SDK, you need to add the following to your AndroidManifest.xml file:

Permissions

 
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.BATTERY_STATS" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

 
Service

 
<service
	android:name="com.qualcommlabs.usercontext.service.GimbalService"
	android:exported="false" >
	<intent-filter>
		<action android:name="com.companyname.applicationname.service.USER_CONTEXT_SERVICE" />
	</intent-filter>
</service>

 
Receivers

 
<receiver
	android:name="com.qualcommlabs.usercontext.service.UserContextServiceStartStopReceiver"
	android:enabled="true" >
	<intent-filter>
		<action android:name="android.intent.action.BOOT_COMPLETED" />
	</intent-filter>
	<intent-filter>
		<action android:name="android.intent.action.ACTION_SHUTDOWN" />
	</intent-filter>
</receiver>

 
Please refer to the documentation included in the Gimbal SDK package for additional information.

Obtaining a Consumer Identity

Next, you need to update MainActivity.java (src/com.companyname.applicationname/MainActivity.java), which should have been generated automatically when you created your Android project. There are two options for obtaining a consumer’s identity. Please refer to the use cases below and add the corresponding code inside your onCreate method.

 
//Inside your onCreate method.
	Koupon koupon = new Koupon(this);
	JSONObject consumerData = new JSONObject();
	try {
	//Optional, add any PII info for the consumer.
	//By default, Koupon will add the UDID of the device to ensure that consumer
		identities are unique.
		consumerData.put("cid", "some identifier");
	} catch (Exception ex) {
		ex.printStackTrace();
	}
	KMRequest km = koupon.createConsumerIdentity(consumerData, null);
//Pass in an AsyncTaskListener. You could do this in two ways (demonstrated below).

 

Implement AsyncTaskListener in the current class

 
//Option #1 implement AsyncTaskListener in the current class
public class MainActivity extends Activity implements AsyncTaskListener {
	@Override
	public void onSuccess(JSONObject result) {
	Log.i("success ", result.toString());
try {
if (result.has("consumer_identity")) {
	consumerId = result.getString("consumer_identity");
	Log.i("consumerId", consumerId);
	Koupon.consumerId = consumerId;
	}
} catch (JSONException e) {
	// TODO Auto-generated catch block
	e.printStackTrace();
}
}
@Override
public void onFailure(JSONObject result) {
	Log.i("fail ", result.toString());
}
@Override
protected void onCreate(final Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	...
//Now pass in "this" as the AsyncTaskListener inside your onCreate method//
	Koupon koupon = new Koupon(this);
	JSONObject consumerData = new JSONObject();
	KMRequest km = koupon.createConsumerIdentity(consumerData, null);
	km.sendRequestAsync((AsyncTaskListener) this);
}

 

Inline

 
//Option #2 inline
@Override
protected void onCreate(final Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	...
	Koupon koupon = new Koupon(this);
	JSONObject consumerData = new JSONObject();
	KMRequest km = koupon.createConsumerIdentity(consumerData, null);
	km.sendRequestAsync(new AsyncTaskListener() {
		@Override
		public void onSuccess(JSONObject result) {
		Log.i(TAG, "SUCCESS: " + result.toString());
		try {
				if (result.has("consumer_identity")) {
				consumerId = result.getString("consumer_identity");
				Log.i(TAG, "consumerId: " + consumerId);
				Koupon.consumerId = consumerId;
				}
			} catch (JSONException e) {
			// TODO Auto-generated catch block
			e.printStackTrace();
			}
		}
		@Override
		public void onFailure(JSONObject result) {
		Log.i(TAG, "Fail: " + result.toString());
		}
});
}

 

(Optional) For the Gimbal SDK

The Koupon Media SDK file GimbalManager.java takes care of enabling the Context Core Connector for you. You don’t need to modify your MainActivity.java file.