eMMa Android SDK Installation Guide · 2013-11-28 · eMMa Android SDK Installation Guide...

eMMa Android SDK Installation Guide

Developer

Contents

Release notes 4

Basic Setup 4

Initial integration 5

Tracking User Behaviour 6

Track Event 6

Using eMMa StartView 8

Check WebView 8

StartView with close button 8

Using eMMa Dynamic Tab 9

Tracking User Stats 11

User’s Login 11

User’s Login and Extras 11

User’s Sign Up 11

User’s Sign Up and Extras 11

Track User’s Extra Info 11

Tracking Purchase for mCommerce 12

Start Order 12

Add Products to the order 12

Track Order 14

Cancel Order 14

Noti!cations 15

Ad Tracker 17

FAQ 18

eMMa is not tracking anything 18

Promoview is not showing 18

Where can I get an App Key? 18

I’m using the Dynamic Tab but it doesn’t work with my own onBackPressed method 18

I want to show a top bar inside the Dynamic Tab 18

Appendix Header 19

Document Revision History 21

© 2013 eMMaSolutions. All Rights Reserved. 3

Release notesVersion 1.5 includes:

• Deprecated C2DM support• New GCM support for push messaging• eMMa AdTracker download reporting

About eMMa SDK Files• eMMa.jar

Basic Setup

eMMa is easy to setup in your project. You only need to follow these points:

1. Add the eMMa.jar !le to your classpath. If you’re using Eclipse, modify your Java Build Path, and choose Add External JAR...If you’re using the SDK tools directly, drop it into your libs folder and the ant task will pick it up.

2. Con!gure AndroidManifest.xml:a. Required Permissions:

android.permission.INTERNETandroid.permission.ACCESS_NETWORK_STATEandroid.permission.READ_PHONE_STATE

b. Optional Permission:android.permission.ACCESS_COARSE_LOCATION or android.permission.ACCESS_FINE_LOCATION If your application has location permissions, eMMa will track where your application is being used.To disable detailed location reporting even when your app has permission, call eMMa.disableReportLocation() before calling eMMa.starteMMaSession() and no detailed location information will be sent.

c. Specify a versionName attribute in the manifest to have data reported under that version name.


Initial integration

In your main Activity, import eMMa:

import com.emma.android.eMMa;

In that class’s onCreate() method add the following call:

eMMa.starteMMaSession(this,"YOURSESSIONKEY");

• If you need to see the eMMa log, enable it by calling:

eMMa.setDebuggerOutput(true);

• To get your SESSION_KEY, please, contact with Elogia.


Tracking User BehaviourWith eMMa you can track everything. Here you’ll !nd the methods that allow tracking custom events that happens on your application.

Track Event

trackEvent(Context ctx, String event);

Use trackEvent to count the number of times certain events happen during a session of your application. This can be useful for measuring how often users perform various actions or create custom segments on eMMa dashboard. Your application is currently limited to counting occurrences for 150 different event ids(maximum length 255 characters).


Using eMMa StartVieweMMa StartView lets you show HTML info on your app startup via a web view. In order to allow them in your app, you need to call !rst the starteMMaSession method.

checkForWebview(Context ctx);

StartView will be presented in the root element and you can use it in the activity’s onCreate() method to show it the !rst time, in the onResume() to show it every time the activity resumes, or whenever you want.

Check WebView

Use checkForWebview in order to check if show StartView added on eMMa dashboard and show it automatically:

eMMa.checkForWebview(this);

StartView with close button

Use checkForWebview in order to check if show StartView added on eMMa dashboard and show it automatically. If you want you can pass a custom Button for using it on the web view.

eMMa.checkForWebviewWithCustomCloseButton(this, myButton);


Using eMMa Dynamic TabeMMa Dynamic Tab lets you show HTML info on your app in a new app section (Only if you use a TabHost or Tabs in the ActionBar of your app).

If you are using a TabHost with Activities:

checkForPromoOnTabHost(Context ctx, TabHost mTabHost, TabSpec mTabSpec);

Use checkForPromoOnTabHost in order to check if show Dynamic Tab added on eMMa dashboard and add it automatically. You can pass the following parameters:

• ctx: Context object.• mTabHost: TabHost where you want to put your new section.• mTabSpec: (Optional) TabSpec for customize your new section

Add the Activity eMMaTabWebView to your AndroidManifest.xml:

. . . <activity android:name="com.emma.android.eMMaTabWebView" android:label="eMMaPromoTab"> </activity></application>

If you are using a TabHost with Fragments or Tabs in the ActionBar:

checkForPromoFragment(eMMaPromoFragmentInterface context);

Use checkForPromoFragment in order to check if show Dynamic Tab added on eMMa dashboard. If added, it will call to the eMMaPromoFragmentInterface’s onAddeMMaTab(String url) method, that you should implement adding the Fragment to your TabManager or TabListener (just like the other Fragments). To create this Fragment you can add to your project the eMMaFragmentWebView class, and pass it the url given.


public class Main extends FragmentActivity implements eMMaPromoFragmentInterface { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); eMMa.starteMMaSession(this, "YOURSESSIONKEY"); eMMa.checkForPromoFragment(this); . . . }

@Override public void onAddeMMaTab(String url) { /* Use one of this methods to create the Fragment and add it to your * TabHost or ActionBar just like the other Fragments. */

//Method 1 Fragment f1 = eMMaFragmentWebView.newInstance(url);

//Method 2 Bundle bundle = new Bundle(); bundle.putString("url", url); String className = eMMaFragmentWebView.class.getName(); Fragment f2 = Fragment.instantiate(this, className, bundle); }}


Tracking User StatseMMa user stats lets you track leads, old foreign users and whatever you want linked to a user in order to create custom segments on eMMa dashboard.

User’s Login

eMMa.loginUserID(this, userId, mail);

LoginUser logs the user on eMMa database for a userId (String) and email (String). When logged

you can use eMMa.loginDefault(this); to log another sign in for the user with the same data.

User’s Login and Extras

eMMa.loginUserID(this, userId, mail, extras);

LoginUser logs the user on eMMa database for a userId (String) and email (String). Also you can pass extra parameters (Map<String,String>) for user in order to have more segmented data. You can add 20 more custom parameters in your Map.

User’s Sign Up

eMMa.registerUserID(this, userId, mail);

RegisterUser set a complete registration from device on eMMa database for a userId (String) and email (String).

User’s Sign Up and Extras

eMMa.registerUserID(this, userId, mail, extras);

RegisterUser set a complete registration from device on eMMa database for a userId (String) and email (String). Also you can pass extra parameters (Map<String,String>) for user in order to have more segmented data. You can add 20 more custom parameters in your Map.

Track User’s Extra Info

eMMa.trackExtraUserInfo(this, extras);

This method update or add extra parameters for current logged user in order to have a better segmentation data. It can be used anywhere.


Tracking Purchase for mCommerceeMMa allows you to track every purchase that you make in your mCommerce.

Start OrderstartOrder(Context ctx, String orderId, String customerId, float totalPrice, String coupon, Map<String,String> extras);

Starts an order for adding products. You can pass the following parameters:

• ctx: Context object (such as an Activity or Service).

• orderID: String with your order id

• customerId: String with your Customer ID. If not passed, eMMa will use the logged one (if exists).

• totalPrice: Float with your total price.

• coupon: String with your coupon if needed.

• extras: Map with until 20 extra parameters, like currency, category...

You can use abbreviated methods if you don’t need all parameters, you can !nd them at the end of the document or in eMMa.jar.

Add Products to the orderaddProduct(String productId, String name, float qty, float price, Map<String,String> extras);

Adds products to your current started order. Always startOrder should be called before. You can pass the following parameters: You can pass the following parameters:

• productId: String with your product id.

• name: String with your product name.

• qty: Float with your product qty.

• price: Float with product price.

• extras: Map with until 20 extra parameters, like currency, category, ...


Track OrdertrackOrder(Context ctx);

Track the current order. It should be called after startOrder and after being all cart products added.

The sequence of tracking order in eMMa is always startOrder>addProduct(*distinct products)>trackOrder

Cancel OrdercancelOrder(Context c, String orderId);

Cancel the order referenced by an order id. If your e-commerce allows canceling orders this method updates the purchases data with the cancelled orders.


Noti!cationseMMa allows you to add a very powerful noti!cation system easy to integrate using the Google Cloud Messaging for Android (GCM). Also allows you to send info through noti!cations and do whatever you want inside your app with it. Please obtain your own Project ID and API key for the GCM as explained on the Getting Started section, and set these parameters for the app in your eMMa account.

In your application, you need to con!gure the AndroidManifest.xml.

Required Permissions:

<permission android:name="your.own.package.permission.C2D_MESSAGE" android:protectionLevel="signature" /><uses-permission android:name="your.own.package.permission.C2D_MESSAGE" /><uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /><uses-permission android:name="android.permission.GET_ACCOUNTS" /><uses-permission android:name="android.permission.VIBRATE" /><uses-permission android:name="android.permission.WAKE_LOCK" />

Also, we have to indicate the eMMa service and receiver that will manage the noti!cation:

. . . <service android:name="com.emma.android.eMMaGCMReceiver" />

<receiver android:name="com.emma.android.GCMBroadcastReceiver" android:permission="com.google.android.c2dm.permission.SEND"> <intent-filter> <action android:name="com.google.android.c2dm.intent.REGISTRATION"/> <action android:name="com.google.android.c2dm.intent.RECEIVE"/> <category android:name="your.own.package" /> </intent-filter> </receiver></application>


http://developer.android.com/guide/google/gcm/index.html

http://developer.android.com/guide/google/gcm/index.html

http://developer.android.com/guide/google/gcm/gs.html

http://developer.android.com/guide/google/gcm/gs.html

Call the method below in your main Activity’s onCreate() method after starting eMMa session:

startPushSystem(Context ctx, int icon);

• ctx: Context object (main Activity).

• icon: (Optional) The resource id of the image you want to show with the noti!cation. If no icon is speci!ed, the noti!cation will use the application icon.

Override the Activity’s onNewIntent() method calling to eMMa.onNewNoti!cation() that will check if the user has received a noti!cation and treat it.

@Override public void onNewIntent(Intent intent) { super.onNewIntent(intent); eMMa.onNewNotification(this, intent); }

Optionally, if you want to control what you receive from push, your Activity has to implement the interface eMMaNoti!cationInterface and the method pushTag(String pushTag) that will be called when the user opens the noti!cation (even if you don’t set a pushTag in the eMMa dashboard).

public class Main extends Activity implements eMMaNotificationInterface { @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); eMMa.starteMMaSession(this, "YOURSESSIONKEY"); eMMa.startPushSystem(this, R.drawable.myicon); . . . }

@Override public void pushTag(String pushTag) { //Do whatever you want with pushTag }}

To disable noti!cations from a device, use eMMa.unregisterPushService(context) and be sure not to call startPushSystem again.

You can use abbreviated methods if you don’t need all parameters, you can !nd them at the end of the document.


Ad TrackerThe Android OS supports URL parameters in download links to Google Play. These parameters can be de!ned in the Ad Tracker view of eMMa dashboard and they will be captured to automatically populate campaign information. This enables the source of the application install to be recorded and associated with future users.

Android will !re an intent called: com.android.vending.INSTALL_REFERRER during the application install process. This occurs before the application is launched for the !rst time. To capture the relevant information:

Add the eMMaReferralReceiver broadcast receiver to yout AndroidManifest.xml:

. . .

<receiver android:name="com.emma.android.eMMaReferralReceiver" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER"/> </intent-filter> </receiver></application>

If you are using your own receiver, perform the following steps:

1. Register the following intent in your broadcast receiver:

<intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER"/></intent-filter>

2. In the onReceive of your receiver class, add the following code:

if (intent.getAction().equals("com.android.vending.INSTALL_REFERRER")) { eMMaReferralReceiver.setInstallReferrer(context, intent);}


FAQ

eMMa is not tracking anythingMake sure that you start an eMMa session using your App Key. eMMa.starteMMaSession call MUST be the !rst eMMa call in your app.

Promoview is not showingAs above, make sure you have started an eMMa session.

Where can I get an App Key?You need to contact with Elogia. They’re nice!

I’m using the Dynamic Tab but it doesn’t work with my own onBackPressed methodCreate a class that implements the eMMaOnBackInterface and pass it as a parameter to the checkPromoOnTabHost method.

I want to show a top bar inside the Dynamic TabThe checkPromoOnTabHost method also admits the id of a view that will be showed above the webview.


Appendix Header///---------------------------------------------------------------------/// Init eMMa///---------------------------------------------------------------------public static void starteMMaSession(Context c, String appKey);

///---------------------------------------------------------------------/// eMMa Configuration///---------------------------------------------------------------------public static String getSDKVersion(); //Get current SDK versionpublic static void setDebuggerOutput(boolean visible); //Show or hide debugger outputs

///---------------------------------------------------------------------/// eMMa User behaviour///---------------------------------------------------------------------//Track eventpublic static void trackEvent(Context c, String event);

///---------------------------------------------------------------------/// eMMa User Stats///---------------------------------------------------------------------

//Loginpublic static void loginUserID(Context c, String userId, String mail, Map<String,String> extras);public static void loginUserID(Context c, String userId, String mail)public static void loginDefault(Context c);

//Register. Lead generationpublic static void registerUserID(Context c, String userId, String mail, Map<String,String> extras);public static void registerUserID(Context c, String userId, String mail);

//Custom segmentationpublic static void trackExtraUserInfo(Context c, Map<String,String> info);

///---------------------------------------------------------------------/// eMMa m-Commerce///---------------------------------------------------------------------

//Start an orderpublic static void startOrder(Context c, String orderId, String customerId, float totalPrice, String coupon, Map<String,String> extras);public static void startOrder(Context c, String orderId, String customerId, float totalPrice, String coupon);public static void startOrder(Context c, String orderId, String customerId, float totalPrice, Map<String,String> extras);public static void startOrder(Context c, String orderId, String customerId, float totalPrice);


public static void startOrder(Context c, String orderId, float totalPrice);public static void startOrder(Context c, String orderId, float totalPrice, String coupon, Map<String,String> extras);public static void startOrder(Context c, String orderId, float totalPrice, String coupon);public static void startOrder(Context c, String orderId, float totalPrice, Map<String,String> extras);//Add products to an existent orderpublic static void addProduct(String productId, String name, float qty, float price, Map<String,String> extras);public static void addProduct(String productId, String name, float qty, float price);

//Track orderpublic static void trackOrder(Context c);

//Cancel order by idpublic static void cancelOrder(Context c, String orderId);

///---------------------------------------------------------------------/// eMMa Promo Web View///---------------------------------------------------------------------

public static void checkForWebview(Context c);public static void checkForWebviewWithCustomCloseButton(Context c, Button button);

///---------------------------------------------------------------------/// eMMa Tab Host View///---------------------------------------------------------------------

public static void checkForPromoOnTabHost(Context c, TabHost mTabHost);public static void checkForPromoOnTabHost(Context c, TabHost mTabHost, TabSpec mTabSpec);

///---------------------------------------------------------------------/// eMMa Notifications///---------------------------------------------------------------------public static void startPushSystem(Context c);public static void startPushSystem(Context c, int icon);


Document Revision HistoryThis table describes the changes to eMMa Android SDK Installation Guide

Date Notes

2012-12-20 New release 1.5.

Deprecated support to C2DM

Support for CGM push messaging


eMMa Android SDK Installation Guide · 2013-11-28 · eMMa Android SDK Installation Guide...

Documents

Transcript of eMMa Android SDK Installation Guide · 2013-11-28 · eMMa Android SDK Installation Guide...