Android integration

Avatar
EMMA Support
Follow

Why use EMMA SDK in your App?

Download and basic integration

Acquisition Integration

Behavior Integration

Push Notifications Integration

Messaging Integration

Depurando el código

 

Why use EMMA SDK in your App?

EMMA SDK offers an unique functionality with the whole user tracking of your App. We have developed a robust, secure and light SDK with more than 2.000 Millions of installs until the day. And, of course, easy to be integrated. 

 EMMA_1.png

EMMA can track the install origin (including Facebook, Twitter & Google), sessions, user events, location, ... with a powerful segmentation unit to evaluate the ROI and your user retention engaging them thanks to our communication tools, Push and In-app Messaging. 

EMMA Android SDK is compatible with all Android devices as of version 4.x.

 

Download and basic integration

 

Android SDK Download

See Changelog

You can download and install EMMA through Gradle.

Use Gradle to download. 

If you are using Gradle's dependency management, you can integrate easily SDK :

  1. Add to /app/build.gradle file repository in which is EMMA.
    repositories {
  maven { url 'http://repo.emma.io/emma' }
}
  2. Add dependency on the same .gradle file. 
    dependencies {
   compile 'io.emma:eMMaSDK:4.2.+'		    
}
  3. If your app already has the com.google.android.gms:playservices-gcm package, you can use your App's dependency and exclude EMMA's dependency. 
    compile ('io.emma:eMMaSDK:4.2.+') {
   exclude group: 'com.google.android.gms'
}
  4. Finally, compile the project with Gradle.

 

Permisos and EMMA SESSION KEY

Currently the SDK contains the following mandatory permissions by default. These permissions do not have to be added in the application's 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_WIFI_STATE" />
<uses-permission android:name="android.permission.GET_ACCOUNTS"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<uses-permission android:name="android.permission.WAKE_LOCK"/>

Add the following meta data to AndroidManifest.xml for Android Advertising ID:

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

If you want to enable localization you have to add the following permissions to your application's AndroidManifest.xml:

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

Add your EMMA SESSION_KEY to AndroidManifest.xml, add to application element:

<meta-data android:name="io.emma.SESSION_KEY" android:value="@string/emma_session_key" />

And in file res/strings.xml add into resources:

<string name="emma_session_key">YOUR_EMMA_SESSION_KEY</string>

Specifies a versionName attribute in the AndroidManifest.xml to have data reported with that version name.

You can get your EMMA Session_Key following this instructions. 

 

Running the SDK & Install Event (Minimum Requirement)

In your Application class, import EMMA:

import io.emma.android.EMMA;

In your application onCreate() method add the following call:

EMMA.getInstance().startSession(this);

Optional

In some cases, It is necessary to change the API EMMA (e.g proxies), this requires add the following method before startSession(...):  

EMMA.getInstance().setWebServiceUrl("https://www.your_proxy_url.com/");

 

Enable Install Referrer

When directing a user to Google Play, the install referrer can be used for 100% tracking accuracy. Your app MUST be setup to allow our SDK to collect the install referrer value and enable the source of the application install to be recorded and associated with future users.

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

Add the eMMaReferralReceiver broadcast receiver to yout AndroidManifest.xml:

<receiver android:name="io.emma.android.referral.EMMAReferralReceiver" android:exported="false">
    <intent-filter>
      <action android:name="com.android.vending.INSTALL_REFERRER"/>
    </intent-filter>
</receiver>

EMMAInstallsBroadcastReceiver

From version 2.5 or later, it includes the EMMAInstallsBroadcastReceiver that allows more than one receiver with com.android.vending.INSTALL_REFERRER action. If the receiver is used you will not have to create an own as explained above. The receiver must be declared as the first receiver of AndroidManifest.xml.

<receiver android:name="io.emma.android.referral.EMMAInstallsBroadcastReceiver" android:exported="false">
    <intent-filter>
       <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

Note: If you are using the Multiple Install BroadcastReceiver of Appsflyer will not need to use the previous receiver.

 

Deploy your App to Google Play

Now you are ready to start tracking with EMMA!

Continue with the advanced integration if you want to extend the EMMA metrics and features.  

*Except Facebook App Installs and Twitter App Promotion

 

Update to version 4

When upgrade to version 4, is mandatory do some minor changes.

Changes in EMMA Session_Key

Initalization method with Session_Key is deprecated.

EMMA.starteMMaSession(this, SESSION_KEY);
EMMA.startEMMASession(this);

Instead, Session_Key must be added to AndroidManifest.xml, you can continue to use the same Session_Key you don't need create a new one.

Edit AndroidManifest.xml, add into application element

<meta-data android:name="io.emma.SESSION_KEY" android:value="@string/emma_session_key" />

And in file res/strings.xml add into resources:

<string name="emma_session_key">YOUR_EMMA_SESSION_KEY</string>

Finally, change initialization by new method.

EMMA.getInstance().startSession(this);

Changes in tracking events

It is deprecated the method:

EMMA.getInstance().trackEvent(Context ctx, String event);

Now, you don't need include a context for track events, replace all uses of deprecated method by new one:

EMMA.getInstance().trackEvent(String event);

 

Acquisition Integration

In the Acquisition section you can have the data of all your campaigns managed with EMMA. 

Here is the specific documentation so you can manage with EMMA your Twitter campaigns and also the detailed documentation to integrate the Powlink functionality.

 

Tracking Twitter App Promotion

EMMA is 100% integrated with Twitter for tracking via AppsFlyer. You will be able to track all the App Installs sources in our Dashboard with no need to integrate Twitter SDKs.

Add the Appsflyer SDK:

 repositories {
	mavenCentral() 
}
....
dependencies {
 compile 'com.appsflyer:af-android-sdk:4+@aar'
}

You need to modify your AndroidManifest.xml file and set a Receiver. Please, modify your AndroidManifest.xml to look like this:

**************** Referral for Facebook and Twitter
<receiver android:name="com.appsflyer.MultipleInstallBroadcastReceiver" android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>
**************** Current EMMA referral
<receiver android:name="io.emma.android.referral.EMMAReferralReceiver" android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER"/>
    </intent-filter>
</receiver>

PLEASE MAKE SURE THE RECEIVER TAG IS WITHIN THE APPLICATION TAG

You need to initialize the SDK on the application’s first launch.

AppsFlyerLib.getInstance().startTracking(this.getApplication(),"<EMMA_KEY>");

In order to track app sessions (opens), please make sure to call this API upon every app session

The EMMA Social Key you have to introduce is the ID to follow the Twitter campaigns.

To get the EMMA Social Key you have to follow these steps: 

1.  Login EMMA website and go to My Account > Configuration > Edit app.

Captura_de_pantalla_2018-10-08_a_las_10.44.51.png

2.  Go to Media Source Settings and fill the App information:  

Captura_de_pantalla_2018-10-08_a_las_10.45.17_copia.png 

To get the App Store ID you can copy the ID of the AppStore link, like this example:

EMMA_4.png

To get Google Play ID you can copy the ID of the GooglePlay link, like this example:

EMMA_5.png

3.  Select the Submit option to keep the changes. 

4.  Send a email to support@emma.io and we will send you the EMMA Social Key.

5. If everything is set up correctly, you will find the Facebook and Twitter campaigns in the Acquisition > AppTracker. Once you start to run the campaigns, the data will automatically enter in EMMA.

EMMA_6.png

 

 

Powlink Integration

To support the Powlink on Android, first of all you need to configure in the EMMA dashboard the subdomain in powlink.io that your app will use, and cover the data of the Google Play ID and the certificate Fingerprint with which you must sign your app in SHA256 format. You can configure this in My Account in the Media Source Settings section of your app. 

4.png

Once you know the subdomain of your Powlinks, you have to add a new filter to the AndroidManifest.xml of your app. This activity is the same used for deeplink process.

 <activity
       android:name="io.emma.android.activities.EMMADeepLinkActivity"
       android:noHistory="true"
       android:theme="@android:style/Theme.NoDisplay">

       <intent-filter>
            <action android:name="android.intent.action.VIEW"/>
            
            <category android:name="android.intent.category.DEFAULT"/>
            <category android:name="android.intent.category.BROWSABLE"/>
                
            <data android:scheme="{YOUR_DEEPLINK_SCHEME}"/>
       </intent-filter>
       
       <intent-filter android:autoVerify="true">
           <action android:name="android.intent.action.VIEW"/>

           <category android:name="android.intent.category.DEFAULT"/>
           <category android:name="android.intent.category.BROWSABLE"/>

            <data
               android:host="subdomain.powlink.io"
               android:scheme="https"/>
    
            <data
               android:host="shortsubdomain.pwlnk.io"
               android:scheme="https"/>

       </intent-filter>
  </activity>

As we explain below in the Deeplink section, you must also add the metadata with the activity to run to treat the url of the powlink.

<meta-data
    android:name="io.emma.DEEPLINK_OPEN_ACTIVITY"
    android:value="com.your.package.CustomDeeplinkActivity"/>

In the Deeplink section it shows how you can handle the Powlinks or Deeplinks received to process them and show the corresponding part of your application.

 

Nota: If you are using a AppTracker with a custom domain (not EMMA default domain: powlink.io), it's necessary add the domain at start the library:

 EMMA.Configuration configuration = new EMMA.Configuration.Builder(this)
               ....
               .setPowlinkDomains("<custom_domain>")
               .setShortPowlinkDomains("<custom_domain>")
               .build();

 EMMA.getInstance().startSession(configuration);

or

EMMA.getInstance().startSession(this);
EMMA.getInstance().setPowlinkDomains("<custom_domain>");
EMMA.getInstance().setShortPowlinkDomains("<custom_domain>");

Behavior Integration

With EMMA you can do a complete integration of the SDK that allows you to know the location of your uses, how they register in the App, how many transactions they do and even their own characteristics. You will obtain all the information about your users in the Behavior section.

The following articles specify the integration of the measurement of each of these aspects:

 

Tracking Events  

In the EMMA platform you have the option to measure between two types of events. Those that the platform includes by default and the Custom events that you want to integrate according to the structure of your application.

Default Events

The EMMA default events allow you to know the Leads (registered users outside the app, old registers and any tags that you want to link to a user in order to be able to create custom segments) and the Login (users that have logged in the App through an existing mail or through some social platform).

Follow these steps to do this integration:

User's Sign Up/Register/Leads

EMMA.getInstance().registerUser(userId, mail);

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

User's Login 

EMMA.getInstance().loginUser(userId, mail);

LoginUser logs the user on EMMA database for a userId (String) and email (String). When logged you can use EMMA.getInstance().loginDefault(); to log another sign in for the user with the same data.

Custom Events

With EMMA you can measure every user action like a custom event: 

EMMA.getInstance().trackEvent(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 30 different event ids.

Events must be created in EMMA dashboard and use the EVENT_TOKEN with the trackEvent method. If you send an event_token wich not exists, EMMA returns an error.

Tracking transactions

EMMA allows you to track every purchase that you make in your mCommerce.

Start Order 

EMMA.getInstance().startOrder(String orderId, String customerId, float totalPrice, String coupon, Map<String,String> extras, String currencyCode);

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

  • orderID

: String with your order id

customerId

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

totalPrice

: Tag with your total price.

coupon

: String with your coupon if needed.

extras

: Map with until 20 extra parameters, like currency, category…

currencyCode

: String with valid Currency Code (EUR,USD,..) If the currency code is not valid EUR currency will be taken

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

Add products to the order 

EMMA.getInstance().addProduct(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

: Tag with your product qty.

price

: Tag with product price.

extras

: Map with until 20 extra parameters, category, …

Track Order

EMMA.getInstance().trackOrder();

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

EMMA.getInstance().startOrder>EMMA.getInstance().addProduct(*distinct products)>EMMA.getInstance().trackOrder()

Cancel Order

EMMA.getInstance().cancelOrder(String orderId);

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

 

Tracking User Tags

Track User's Extra Info

EMMA.getInstance().trackExtraUserInfo(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.

If you want to use the EMMA RULE On his Birthday send us the date of the user birthday with the following format: 

Name: BIRTHDAY

Value: YYYY-MM-DD

Info

Remember to check the SDK logs to see the list of TAGS that can't be used because they are reserved for the EMMA system. 

 

Tracking 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.disableTrackingLocation() before calling EMMA.startSession(this) and no detailed location information will be sent.

 

Get User Info

Get User ID

EMMA.getInstance().getUserID();

This method will return the user’s EMMA ID. This ID is unique for each user and can be used to filter when using mobactions push, start view and dynamic tags.

Your Activity has to implement the interface eMMaUserInfoInterface and the method OnGetUserID(int id) that will be called when the id of the user is available.

Get User Info

EMMA.getInstance().getUserInfo();

This method will return the user’s info on EMMAa in JSON format.

Your Activity has to implement the interface eMMaUserInfoInterface and the method OnGetUserInfo(JSONObject json) that will be called when the information of the user is available.

The JSON will include the following parameters: 

id The same ID than previous method (eMMa.getUserID)
udid Unique ID per app installation
emma_build EMMA version"]">Build identifier of the current EMMA version
email Email of the user in case that register or login methods are implemented
customerid Id of the user returned by register and login methods if exists
created_at When the user was created
updated_at Last time user updated its info
registred_at When user got registered on app (if register method is implemented)
fisrt_login When user got logged on app for first time (if login method is implemented)
last_login When user got logged on app for last time (if login method is implemented and it’s allowed to the user make more than one login)
device User’s device
app_version  Version of the app
os_version  Version of the Operate System
rated If user has rated the app
token Push token
inactive If user has deactivated the push service
latitude  User's latitude in case geolocation is activated
longitude  User's longitude in case geolocation is activated
emma_city  User's city in case geolocation is activated
emma_country  User's country in case geolocation is activated
emma_state  User's statate in case geolocation is activated
emma_device_id Unique device ID
emma_referrer_id ID of the campaign that user came from (if AppTracker is used)
loyal_user_at When the user became loyal
loyal_buy_at When the user became a loyal buyer
emma_num_sessions User’s num session
last_session_at User’s last session
tag_name Name and value of all the custom tags of the user

Also, if the user came from a Facebook campaign, we include the following parameters:

eat_sub1 App Name
eat_sub2 "facebook" (Fixed value)
eat_sub3 "Facebook's Campaign" (Fixed value)
eat_sub4 "cpi" (Fixed value)
eat_sub5 Facebook campaign name
eat_sub6 Facebook campaign ID
eat_sub7 Facebook adgroup name
eat_sub8 Facebook adgroup ID
eat_sub9 Facebook adset name
eat_sub10 Facebook adset ID

In case of user came from AppTracker, the JSON may include following custom parameters.

To use this method you need to buy the Raw Export feature in My Account > My Plan. 

 

Installation attribution information

Through the method explained below, you can to obtain the installation attribution data for each user, obtaining the following information:

  • Status {String}:Return the attribution state. This can have various types:
    • pending: The installation is still pending attribution, this is due to the attribution window, maximum 2 days).
    • campaign: It means that the installation has been attributed to a specific campaign, source and provider.
    • organic:The installation has been organic. If the attribution is organic, it means that installation won't be linked to one campaign, therefore the campaign will be null.
  • Campaign ID {Number}
  • Campaign name {String}
  • Source ID {Number}
  • Source name {String}
  • Provider ID {Number}
  • Provider name {String}

In order to obtain this information about installation attribution, its necessary to add the following method:

EMMA.getInstance().getInstallAttributionInfo(attribution -> {
    final EMMAInstallAttribution attr = attribution;
    if (attr != null) {
        // process attribution
    }
 });

 

Push Notifications integration

NOTE: To differentiate a notification from our push system to other systems, the payload sent by EMMA contains a flag called "eMMa".

EMMA allows you to add a very powerful notification system easy to integrate using the Google Cloud Messaging for Android (GCM).

Please obtain your own Project Number and API key for the GCM as explained this post, and set these parameters for the app in your EMMA account.

IMPORTANT: Use the Server API Key for GCM, not the Browser nor the Simple API Access.

Version 4.2 add changes about this section: 

In your application, you need to configure the AndroidManifest.xml.

Required permissions:

<uses-permission android:name="{your_own_application_id}.C2D_MESSAGE"/>
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE">
<permission
    android:name="{your_own_application_id}.permission.C2D_MESSAGE"
    android:protectionLevel="signature"/> 

Also, you have indicate to EMMA the receiver which will manage the notification:

<receiver
    android:name="io.emma.android.push.EMMAGCMBroadcastReceiver"   
    android:permission="com.google.android.c2dm.permission.SEND">
    <intent-filter>        
        <action android:name="com.google.android.c2dm.intent.RECEIVE"/>      
        <category android:name="{your_own_application_id}"/>   
    </intent-filter>
</receiver>

EMMAPushBroadcastReceiver is deprecated. You can remove it.

For the token to refresh when it was expired, add the following service to AndroidManifest.xml:

<service
    android:name="io.emma.android.push.EMMAInstanceIDListenerService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.android.gms.iid.InstanceID"/>
    </intent-filter>
</service>

Init the push engine below start session:

@Override
public void onCreate() {
   super.onCreate();
   EMMA.getInstance().startSession(this);
   EMMA.getInstance().startPushSystem(MyActivity.class, R.drawable.icon, customDialog);
}
MyActivity.class 

: Activity you want to be opened when push is received.

R.drawable.icon

: (Optional) The resource id of the image you want to show with the notification. If no icon is specified, the notification will use the application icon.

customDialog

: (Optional) Set to true if you want to use your custom dialog.

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

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

Note: onNewNotification has a boolean parameter that checks if notification push contains a Rich Push Url.

For check Rich Push Url when app is opened through push notification:

public class YOUR_ACTIVITY extends Activity{

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        EMMA.getInstance().checkForRichPushUrl();
    }

Note: richPushUrl can be used in any part of app.

If your application is WebView-based, you have to add the checkForRichPushUrl in the next method:

webView.setWebViewClient(new WebViewClient(){
.......

@Override
public void onPageFinished(new WebViewClient() {
    EMMA.getInstance().checkForRichPushUrl();
});

Optionally, if you want to control what you receive from push, your Activity has to implement the interface EMMANotificationInterface and the methods pushTag(String pushTag) and pushMessage(String message) that will be called when the user opens the notification (even if you don’t set a pushTag in the EMMA dashboard). You can also declare if you want to show the EMMA Dialog or your own custom Dialog.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  EMMA.getInstance().getNotificationInfo();
}
@Override
public void pushTag(String pushTag) {
//Do whatever you want with pushTag
}
@Override
public void pushMessage(String message) {
//Create your own dialog with the push message
}
To disable notifications from a device, use EMMA.getInstance().unregisterPushService() and be sure not to call EMMA.getInstance().startPushSystem(...) again.

You can use abbreviated methods if you don’t need all parameters, you can find them here.

Push Image

You can select the color for notification icon background, including the following line of code

EMMA.getInstance().startPushSystem(PushActivity.class, R.drawable.notification_icon,
ContextCompat.getColor(this, R.color.colorPrimary), true);

Rich Push, custom sounds in push notifications. Required SDK version 2.5.5 or later

You need to add your sound files into the raw folder of your app's res folder. Remember use the same name for sound files in iOS and Android.

Rich Push URL use DeepLinking

You can redirect your push notifications openings a section into your app. For that you can use a structure like this

scheme://host/page1/page2/page3...

In order to make your app available to receive a scheme deep link:

1) Add the following activity into your AndroidManifest.xml:

<activity
    android:name="io.emma.android.activities.EMMADeepLinkActivity"
    android:theme="@android:style/Theme.NoDisplay">

    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>

        <category android:name="android.intent.category.DEFAULT"/>
        <category android:name="android.intent.category.BROWSABLE"/>

        <data android:scheme="YOUR_SCHEME"
                    android:host="YOUR_HOST"/>
    </intent-filter>
</activity>

2) Add the activity will be launched, in the form of metadata, inside the tag <application></application> into AndroidManifest.xml. This activity will be launched when the SDK execute a deep link:

<meta-data
    android:name="io.emma.DEEPLINK_OPEN_ACTIVITY"
    android:value="com.your.package.CustomDeeplinkActivity"/>

Remember that in case of an activity that can be found open in the app when a deep link is executed, it has to be declared in the AndroidManifest.xml as singleTask:

<activity
    android:name=".activities.MainActivity"
    android:launchMode="singleTask" />

In this case, if the activity is in the stack when the deep link is executed, the attempt with the information of this will come to the method of the onNewIntent activity. In case of not having the "launchMode" as singleTask causes the activity to be instantiated again, which causes duplications.

3) In order for the deep link that is entered in the Rich Push URL field (in the EMMA dashboard) to execute correctly, it is important to add the following method in the activity that is opened by the push or any other that is consequent with it, but to run when you open the app from the notification

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    EMMA.getInstance().checkForRichPush();
}
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    EMMA.getInstance().onNewNotification(intent, true);
}

The checkForRichPush and onNewNotification method checks the Rich Push field sent in the notification payload and performs the relevant actions. If it is a deep link, it will be executed by opening the activity defined in the AndroidManifest.xml metadata.

4) Define the behavior of the activity to open the deep link. In this case CustomDeepLinkActivity:

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

         if (getIntent() != null && getIntent().getData() != null){
             processDeepLink(getIntent().getData());
         }
         finish();
    }
    private void processDeepLink(Uri uri){
        if (uri != null && uri.getHost().equals("home")){
           goHome();
        }
    }

    @Override
    public void onNewIntent(Intent intent){
        processDeepLink(intent.getData());
    }

5) Finally, add under the startPushSystem method, you must add YOUR_SCHEME:

    EMMA.getInstance().setDeepLinkSchemes(YOUR_SCHEME);
 

IMPORTANT: follow these steps to get the Google Server Key:

1. Go to the Firebase web.

2. If you are not registered, you have to do it with a Google account and then you have to GO TO CONSOLE 

server_1.png

3. Create a new project:   

server_2.png

4. Once you create it, go to the Project Settings section

server_3.png

5. Go to CLOUD MESSAGING section 


server_4.png


6. Copy the Server Key and Sender ID values: 

server_5.png

7. Go back to EMMA and go to the My Account section. Paste the values you copied in the previous step in the Android section of your app's settings:  

server_6.png

 

Messaging Integration

Messaging includes six different communicative formats that you can integrate to impact your users:

In many of these communicative formats you can delete the redirection url's that you want to introduce. With the EMMA Whitelist functionality you can define what content you want to be displayed in the scheduled webviews.  

Review Campaign 

EMMA.getInstance().getInAppMessage(EMMACampaign.Type type);

Use inAppMessage to confirm whether the Campaign created on the EMMA platform corresponding to the specified Type is displayed.

Campaign with tag

EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setLabel("label");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.BANNER, inAppRequest);

If you wish you can pass a custom String that will tag the Campaign in case you use more than one Campaign of the same type in your app and you need to distinguish them.

Add interface

EMMA.getInstance().addInAppMessageListener(new EMMAInAppMessageInterface() {
    @Override
    public void onShown(EMMACampaign campaign) {
        
    }

    @Override
    public void onHide(EMMACampaign campaign) {

    }

    @Override
    public void onClose(EMMACampaign campaign) {

    }
});

EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setLabel("label");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.BANNER, inAppRequest);

If you wish you can add an interface (or several) to receive the different events related to the Campaigns of your app.

 

Using EMMA Banner 

EMMA Banner lets you show a banner on your app with promotional info. The banner will be shown and hidden depending on your dashboard configuration. If you press the banner a web view with HTML content will be shown.

EMMA_13.png

Check Banner

EMMA.getInstance().getInAppMessage(EMMACampaign.Type.BANNER); 

 

Using EMMA Startview 

EMMA StartView lets you show HTML info on your app startup via a web view.

EMMA_14.png

In order to allow them in your app, you need to call first the startSession method.

Check Startview

EMMA.getInstance().getInAppMessage(EMMACampaign.Type.STARTVIEW);

 

Using EMMA Adball 

EMMA AdBall lets you show an AdBall Icon on your app that you can move freely around the app view and also hide it. If you press the AdBall a popup with HTML content will be shown.

EMMA_15.png

 In order to allow them in your app you need at least implement the first method.

Check AdBall

EMMA.getInstance().getInAppMessage(EMMACampaign.Type.ADBALL);

 

Using EMMA Dynamic Tab

Currently this functionality is not available for Android. 

 

Using EMMA Strip

EMMA Strip lets you show a Strip above the status bar with a message for your customers. It can be placed in any part of the app

EMMA_17.png

 Check Strip

EMMA.getInstance().getInAppMessage(EMMACampaign.Type.STRIP);

 

Using EMMA Coupons

EMMA Coupons allows you to obtain, verify, redeem coupons that are defined and configured on the EMMA platform.

EMMA_18.png

Get Coupons 

EMMA.getInstance().addCouponsCallback(new EMMACouponsInterface() {
    @Override
    public void onCouponsReceived(List<EMMACoupon> coupons) {
        
    }

    @Override
    public void onCouponsFailure() {

    }

    @Override
    public void onCouponRedemption(boolean success) {

    }

    @Override
    public void onCouponCancelled(boolean success) {

    }

    @Override
    public void onCouponValidRedeemsReceived(int numRedeems) {

    }
});
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.COUPON);

With this call, we will get all the Coupons information available to the user, depending on the conditions that have been set on the EMMA platform.

A list of the existent coupons it will return, listing the automatic coupons first, from newer to older, and then, listing the classic coupons from newer to older too. 

EMMACouponsInterface.onCouponsReceived(List<EMMACoupon>) is called in the case that the user has available coupons to redeem, or to EMMACouponsInterface.onCouponsFailure() if the user has no available coupons.

EMMACoupon contains all the information about the coupon: id (EMMA internal identifier), code, maximum number of redemptions, number of times traded, title, description, picture ...

If you want to send information to EMMA when the coupon has been clicked or when it is displayed on the screen, the following methods must be added when both actions are performed in the app:

EMMA.getInstance().sendInAppImpression(CommunicationTypes.COUPON, couponCampaign);
EMMA.getInstance().sendInAppClick(CommunicationTypes.COUPON, couponCampaign);

Once the coupon is painted on screen it is necessary to call this method

Details of a Coupon

EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.COUPON, inAppRequest);

With this call, we will get information about a particular coupon.

The couponId parameter must be the EMMA internal identifier of a coupon, ID that can be obtained from a call to getCoupons made ​​earlier.

getCoupon calls to eMMaCouponsInterface.onSingleCouponReceived (eMMaCoupon) in case the indicated coupon exists or otherwise to eMMaCouponsInterface.onCouponsFailure().

EMMACoupon contains all the information about the coupon: id (EMMA internal identifier), code, maximum number of redemptions, number of times traded, title, description, picture ...

Check the Coupon validity 

EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.COUPON_VALID_REDEEMS, inAppRequest);

With this call, we can check if the user can redeem the indicated coupon.

The couponId parameter must be the EMMA internal identifier of a coupon, ID that can be obtained from a call to getCoupons made ​​earlier.

getCouponValidRedeems calls to eMMaCouponsInterface.onCouponValidRedeemsReceived (int numRedeems), where numRedeems indicates the number of times it can still be redeemed the coupon or -1 in case of error.

Redeem a coupon

EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.REDEEM_COUPON, inAppRequest);

With this call, the user redeems the indicated coupon.

The couponId parameter must be the EMMA internal identifier of a coupon, ID that can be obtained from a call to getCoupons made ​​earlier.

redemmCoupon calls EMMACouponsInterface.onCouponRedemption(boolean success), where success indicates if the coupon has redeemed.

Cancel a coupon

EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setInAppMessageId("couponId");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.CANCEL_COUPON, inAppRequest);

This call can cancel the redemption of a coupon that has done before.

The couponId parameter must be the EMMA internal identifier of an identifier coupon that can be obtained from a call to getCoupons made ​​earlier.

cancelCoupon calls to eMMaCouponsInterface.onCouponCancelled (boolean success ), where success indicates if the coupon is canceled.

Note

511 error reports that the redeem could not be completed for some reason. Some possible causes could be the interruption of the connection with the DB or multiple redemptions affected by a capping. In these cases, we recommend to treat this error and warn the end user. 

 

Using EMMA NativeAd

EMMA NativeAd allows you to obtain the information of a NativeAd corresponding to a template that has been defined and configured on the EMMA platform.

Formatos-integracion-android.png

Get NativeAd 

EMMANativeAdInterface nativeAdInterface = new EMMANativeAdInterface() {
    @Override
    public void onReceived(EMMANativeAd nativeAd) {
        
    }

    @Override
    public void onShown(EMMACampaign campaign) {

    }

    @Override
    public void onHide(EMMACampaign campaign) {

    }

    @Override
    public void onClose(EMMACampaign campaign) {

    }
};
EMMAInAppRequest inAppRequest = new EMMAInAppRequest();
inAppRequest.setNativeAdTemplateId("myTemplateId");
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.NATIVEAD, inAppRequest, nativeAdInterface); 

With this call, we will get all the information of the NativeAd available to the user regarding the templateId, according to the conditions that have been configured on the EMMA platform.

EMMANativeAdInterface.onReceived(EMMANativeAd nativeAd) is called if there is a NativeAd corresponding to the corresponding template identifier ("myTemplateId").

EMMANativeAd contains all the fields configured in EMMA for this NativeAd template, to obtain them the following method will be used:

@Override
public void onReceived(EMMANativeAd nativeAd) {
    try {
        String title = nativeAd.getField("Title");
    } catch (EMMAFieldNotFoundException e) {
        //Esta Exception se la lanzará cuando el nativeAd no contenga ningún campo con el nombre indicado
        e.printStackTrace();
    }
}

Once you have obtained all the required fields, you can already create the view to paint this NativeAd on the screen depending on the design that you want to apply. Once the NativeAd is displayed it is necessary to call this method:

EMMA.getInstance().sendInAppImpression(CommunicationTypes.NATIVE_AD, nativeAd);

Open a NativeAd

EMMA.getInstance().openNativeAd(nativeAd);

With this call, the content of the link configured in the NativeAd from the EMMA platform will be displayed.

Multiple NativeAds

There are a new callback in Android to manage the new multiple Native Ad. This callback is call EMMABatchNativeAdInterface and extends the EMMAInAppMessageInterface. The same as the callback for the return of the Native Ad unique. 

public interface EMMABatchNativeAdInterface extends EMMAInAppMessageInterface {
    void onReceived(List nativeAds);
}

To multiple Native Ad, it will be use a EMMAInAppRequest subclass, EMMANativeAdRequests. Until now, the ID template parameter was in the EMMAInAppRequest class, now, it will be depreecated in this and will be a parameter of the EMMANativeAdRequest subclass. It can be used both ways, but the correct way to use it will be in the subclass. 

Multiple NativeAd (returns all the available Native Ad for a Template) [Since 4.2.5 iOS SDK version onwoards] 

EMMANativeAdRequest requestParams = new EMMANativeAdRequest();
requestParams.setTemplateId(BATCH_NATIVE_AD_TEMPLATE2);
requestParams.setBatch(true);

EMMA.getInstance().getInAppMessage(EMMACampaign.Type.NATIVEAD, requestParams, this);

Unique NativeAd (deprecated)

EMMAInAppRequest requestParams = new EMMAInAppRequest();requestParams.setNativeAdTemplateId(NATIVE_AD_TEMPLATE2); 
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.NATIVEAD, requestParams, this);

Unique NativeAd (returns the most recent Native Ad available from the template)

EMMANativeAdRequest requestParams = new EMMANativeAdRequest();
requestParams.setTemplateId(NATIVE_AD_TEMPLATE2);
EMMA.getInstance().getInAppMessage(EMMACampaign.Type.NATIVEAD, requestParams, this)

The difference is that the parameter batch it will have to be set to true in case you want a multiple reception of Native Ad. By default, this value will be false.

Once you have the Native Ad, the EMMANativeAd class will have a new tag field of type string that can be nil or contain the string with tag. The method is called getTag().

 

 

EMMA Whitelist

Minimum SDK version: 2.5.6 or later

With this functionality we can limit the urls the EMMA will open so in the In-App communication will only be displayed the content that begins with any of the url's we have indicated in the whitelist.  

If we don't indicate any url in the whitelist, any url will be displayed.

This functionality will affect to the a los Push (Rich URL), Banners, StartViews, AdBalls and DynamicTabs.

In the communications (Banners, StartViews, AdBalls y DynamicTabs) you can upload external content to the app via Webview, and for Banners, AdBalls and DynamicTabs you could upload external images that would also be controlled by the whitelist.

If you want to send a push with Rich URL, if it does not comply, the corresponding Webview would not be opened but the push does arrive to the application. It should be noted that if instead a url you use a deeplink, the deeplink scheme must be added to the whitelist in order to open it. 

How to use it

We should call this method after the starteSession and before we call any other method of the In-App communications.

EMMA.getInstance().setWhitelist(List<String> urls);

Examples

 If my whitelist is “http://mydomain.com”.

List<String> whitelist = Arrays.asList("http://mydomain.com");
EMMA.getInstance().setWhitelist(whitelist);

Example 1:

Set up in the EMMA dashboard a Banner with Target URL https://mydomain.com

The Banner will be not displayed, we should add to the whitelist: https://mydomain.com

Example 2:

Set up in the EMMA dashboard a StartView with StartView URL http://www.mydomain.com

The Startview will be not displayed, we should add to the whitelist: https://mydomain.com

Example 3:

Set up in the EMMA dashboard a Banner with Target URL http://mydomain.com/my/url and SmartPhone Banner URL http://subdomain.mydomain.com/my/image

The Banner will be not displayed, the image url isn't in the whitelist, we should add to the whitelist http://subdomain.mydomain.com

Example 4:

Set up in the EMMA dashboard a Banner with Target URL http://mydomain.com/my/url/

The Banner will be displayed because the url that we introduce in the Target URL starts with the same protocol and domain that the whitelist url.  

Example 5:

Set up in the EMMA dashboard a Startview with StartView URL http://mydomain.com/mypage.html&param=value

The StartView will be shown because the url that we introduce in the StartView URL option starts with the same protocol and domain that the whitelist url. 

 

Debugging your code

This step is optional. If you need to see the EMMA log, enable it (before starteSession) by calling:

EMMA.getInstance().setDebuggerOutput(true);

Please consider that EMMA is not real time. A delay of 1 hour can occur to see your data. 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.