Download and basic integration
- Android SDK Download
- Permissions and EMMA SESSION_KEY
- Running the SDK & Install Event (Minimum Requirement)
- Activate Install Referrer
- Deploy your App to Google Play
- Update to version 4.5
- Update to version 4.6
- Tracking Events
- Tracking User Tags
- Tracking Location
- Get user info
- Installation attribution information
Push Notifications Integration
- Using EMMA Banner
- Using EMMA Startview
- Using EMMA Adball
- Using EMMA Dynamic Tab
- Using EMMA Strip
- Using EMMA Coupons
- Using EMMA NativeAd
- EMMA Whitelist
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 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 with version 4.0.3 (Ice Cream Sandwich MR1) or higher.
Download and basic integration
Android SDK Download
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 :
- Add to /app/build.gradle file repository in which is EMMA.
repositories { maven { url 'https://repo.emma.io/emma' } }
Important
To use https it is important to have a version of Java 7>= 7u111 and / or Java 8 >= 8u101 installed.
If you do not have a compatible version, you can download a recent version of java from the following link:
https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
Or use the following url: https://repo.emma.io/emma - Add dependency on the same .gradle file.
dependencies { implementation 'io.emma:eMMaSDK:4.7.+' }
- Finally, compile the project with Gradle.
Permissions 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.VIBRATE"/>
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">example0ikl98</string>
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.5
Changes in events
The following methods are deprecated in version 4.4 and removed in 4.5 and later:
EMMA.getInstance().trackEvent(String token, Map<String, Object> attributes) EMMA.getInstance().trackEvent(String token)
Both are replaced by the following method:
EMMA.getInstance().trackEvent(EMMAEventRequest eventRequest)
Changes in inapp
The following methods are deprecated in version 4.4 and removed in 4.5 and later:
EMMA.getInstance().getInAppMessage(EMMACampaign.Type campaignType) EMMA.getInstance().getInAppMessage(EMMACampaign.Type campaignType, EMMAInAppRequest request)
EMMA.getInstance().getInAppMessage(EMMACampaign.Type campaignType, EMMAInAppRequest request, EMMAInAppMessageInterface listener)
Both are replaced by the following method:
EMMA.getInstance().getInAppMessage(EMMAInAppRequest params)
EMMA.getInstance().getInAppMessage(EMMAInAppRequest requestParams, EMMAInAppMessageInterface listener)
Push Options (added in version 4.3)
The following methods are deprecated (removed in 4.5 and later):
public void startPushSystem(Class activityClass, int icon) public void startPushSystem(Class activityClass, int icon, int notificationColor) public void startPushSystem(Class activityClass, int icon, boolean customNotification) public void startPushSystem(Class activityClass, int icon, int notificationColor, boolean customNotification)
Both are replaced by:
public void startPushSystem(EMMAPushOptions pushOptions)
Example:
EMMAPushOptions pushOpt = new EMMAPushOptions.Builder(PushActivity.class, R.drawable.notification_icon) .setNotificationColor(ContextCompat.getColor(this, R.color.colorPrimary)) //Optional .setNotificationChannelId("custom id") //Optional .setNotificationChannelName("custom channel") //Optional
Update to version 4.6
The pushMessage and pushTag methods have been removed from the EMMANotificationInterface interface and the onPushOpen method has been added. This method is passed the push campaign that has been opened at that time. This campaign has attributes such as tag or message, which would replace deleted methods.
@Override
public void onPushOpen(EMMAPushCampaign pushCampaign)
Acquisition Integration
In the Acquisition section you can have the data of all your campaigns managed with EMMA.
Here is the specific documentation
to integrate the Powlink functionality.Tracking Twitter App Promotion
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.
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 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
Info
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 Firebase Cloud Messaging.
Important
Please obtain your own Sender Id and Server key for the FCM as explained this post, and set these parameters for the app in your EMMA account.
To integrate Firebase in your app follow these steps:
-
Add the following service to AndroidManifest.xml:
-
Add the following dependency to the build.gradle located at the root of the project:
In the build.gradle of the app add the Firebase dependency:
- Add the google-services.json in the /app directory within the project. You can get more info here to know hot to get the file. Without this file push notifications will not work, it is mandatory to add it.
- In the case of using a key server "Legacy" is still valid and supported by Google, although it is recommended to use the FCM Server Key.
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 SampleActivity 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);
Messaging Integration
Messaging includes six different communicative formats that you can integrate to impact your users:
- Using EMMA Banner
- Using EMMA Startview
- Using EMMA Adball
- Using EMMA Dynamic Tab
- Using EMMA Strip
- Using EMMA Coupons
- Using EMMA NativeAd
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.
Campaign parameters
A new feature has been added for communications campaigns, you can now receive previously configured parameters in the dashboard. To receive these parameters it is necessary to use the EMMAInAppMessageListener callbacks. The parameters go inside the EMMACampaign object as an attribute called params.
@Override
public void onShown(EMMACampaign campaign) {
Map<String, String> params = campaign.getParams();
// tratar params
}
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.
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.
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.
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
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.
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.
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¶m=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.
0 Comments