To add cordova plugin execute following command:
$ ionic cordova plugin add cordova-plugin-emma-sdk --variable ADD_PUSH=1
Once the installation is complete, src/app/app.component.ts add the following code:
import { Component } from "@angular/core";
import { AlertController, Platform } from "@ionic/angular";
declare var window: any;
@Component({
selector: 'app-root',
templateUrl: 'app.component.html'
})
export class AppComponent {
constructor(
private platform: Platform,
private alertCtrl: AlertController
) {
this.initializeApp();
}
initializeApp() {
this.platform.ready().then(() => {
this.initEMMA();
});
}
initEMMA() {
const EMMA = window.plugins.EMMA;
const configuration= {
sessionKey: '<SESSIONKEY>',
debug: true
};
EMMA.startSession(configuration);
}
}
The latest version of the Cordova SDK is 1.10.0.
Firebase to be able to use FCM. https://firebase.google.com/docs/android/setupFor the notification received in Android to have an image we have to add in the config.xml which will be the notification icon used:
<resource-file src="resources/android/notification/drawable-mdpi-notification.png" target="app/src/main/res/drawable-mdpi/notification.png" />
<resource-file src="resources/android/notification/drawable-hdpi-notification.png" target="app/src/main/res/drawable-hdpi/notification.png" />
<resource-file src="resources/android/notification/drawable-xhdpi-notification.png" target="app/src/main/res/drawable-xhdpi/notification.png" />
<resource-file src="resources/android/notification/drawable-xxhdpi-notification.png" target="app/src/main/res/drawable-xxhdpi/notification.png" />
<resource-file src="resources/android/notification/drawable-xxxhdpi-notification.png" target="app/src/main/res/drawable-xxxhdpi/notification.png" />
To activate the push it is necessary to add the configuration file google-services.json from the firebase project to the file config.xml:
<!-- Google services JSON from Firebase -->
<resource-file src="google-services.json" target="app/google-services.json" />
To be able to receive the push it is necessary to add the following service inside the AndroidManifest of the application by adding the following code in the config.xml file:
<config-file parent="/manifest/application" target="AndroidManifest.xml" xmlns:android="http://schemas.android.com/apk/res/android">
<service android:enabled="true" android:exported="false" android:name="io.emma.android.push.EMMAFcmMessagingService">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
</config-file>
To initialize the push in the App, it is necessary to call the startPush method once the deviceReady event has been received within the app.component.ts file.
To integrate attribution it is necessary to configure DeepLink and AppLink in the app.
{custom_scheme} must be replaced with the chosen schema name. Normally the chosen name has to do with the name of the app.
{basic_deeplink_scheme} replace with the basic deeplink schema e.g. emmaionic.
{config_id} must be replaced by the id of the widget tag inside the config.xml file e.g. my.company.com.
In order for the app to open when running a DeepLink or AppLink, the following needs to be added to config.xml:
singleTask mode to config.xml:<config-file parent="/manifest/application" target="AndroidManifest.xml" xmlns:android="http://schemas.android.com/apk/res/android">
<activity android:exported="true" android:name="io.emma.android.activities.EMMADeepLinkActivity" android:noHistory="true" android:theme="@android:style/Theme.NoDisplay">
<intent-filter 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="{custom_scheme}.powlink.io" android:scheme="https" />
</intent-filter>
<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="{basic_deeplink_scheme}" />
</intent-filter>
</activity>
<meta-data android:name="io.emma.DEEPLINK_OPEN_ACTIVITY" android:value="{config_id}.MainActivity" />
</config-file>
Once this is added in the configuration it is necessary to add the event in the main component. This method is where the logic to process the link is added.
this.platform.ready().then(() => {
document.addEventListener('onDeepLink', (event) => {
//process deeplink and applink
});
...
In case you are using your own deeplink callback, ignore the previous part and add the opening intent-filters to your configuration activity:
<intent-filter 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="{custom_scheme}.powlink.io" android:scheme="https" />
</intent-filter>
<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="{basic_deeplink_scheme}" />
</intent-filter>
Add the EMMA.handleLink method to process the link and send the click to EMMA.
document.addEventListener('myCustomCallback', (event) => {
const url = event.url;
EMMA.handleLink(url);
});
To activate the localization it is necessary to add the following permissions to the config.xml:
<config-file parent="/manifest" target="AndroidManifest.xml" xmlns:android="http://schemas.android.com/apk/res/android">
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</config-file>
Once the location has been added, it can be activated with the EMMA.trackLocation() method.
To activate the Push functionality you will only have to call the EMMA.startPush() method in onDeviceReady.
To correctly configure this functionality we will use the same dependencies as the Powlink integration in the native SDK: https://developer.emma.io/es/ios/integracion-sdk#dependencias-1
Once the dependencies are configured, it is necessary to add the event in the main component.
document.addEventListener('onDeepLink', (event) => {
const url = event.url;
});
To integrate SKAdNetwork see the native documentation here.
To use the localization it is necessary to add the following permissions in the Info.plist file of the App:
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs location access</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>$(PRODUCT_NAME) needs location access</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>$(PRODUCT_NAME) needs location access</string>
To request the IDFA, the following permission needs to be added to the Info.plist:
<key>NSUserTrackingUsageDescription</key>
<string>Uso del indentificador para redes de terceros</string>
We start the session using the startSession method.
EMMA.startSession(configuration);
The configuration parameters for the login:
| Parameter | Type | Description |
|---|---|---|
| sessionKey | string | Key for identification at login. |
| apiUrl | string (Optional) | Add the url if a proxy is used. |
| queueTime | int (Optional) | Time to empty the transaction queue. |
| isDebug | boolean (Optional) | Enable/disable logging in the SDK. |
| customPowlinkDomains | string[] (Optional) | Add domains if the app uses custom domains in EMMA (subdomains that are configured in app preferences are not custom domains). |
| customShortPowlinkDomains | string[] (Optional) | Add the short domains if the app uses custom domains in EMMA (the subdomains that are configured in the app preferences are not custom domains). |
| trackScreenEvents | boolean (Optional) | Enable/disable automatic screen tracking. |
Add the startPush method after startSession:
const pushOptions = {
classToOpen: 'io.emma.cordova.exampleionic.MainActivity',
iconResource: 'notification'
};
this.EMMA.startPush(pushOptions);
startPush parameters:
| Parameter | Type | Description |
|---|---|---|
| classToOpen | string | Indicates the opening activity in the case of clicking on the notification, in RN it is normal to have only one main activity so we add this one, for this we always indicate it with the absolute path {packageName}.MainActivity. |
| iconResource | string | The icon that will contain the notification in the status bar and in the notification menu. The SDK looks for this icon in the drawable or drawable-xxx folder, so it is important that the name included in this parameter matches the drawable png. |
| color | string (Optional) | Colour in hexadecimal format. |
| channelId | string (Optional) | If the application uses an existing notification channel, otherwise it will create a new one. |
| channelName | string (Optional) | Add the name of the new channel. |
The use of
startPushis valid for Android and iOS, although the parameters are only used in Android since in iOS it takes the default values of the App.
EMMA allows the sending of custom events and several default events, the default Open event is sent when logging into the SDK, but the login and registration events are events that need to be added to the application code.
I use the following method to send events:
eventToken : EventParams ={
eventRequest: "7b358954cf16bc2b7830bb5307f80f96",
eventAttributes: {IONIC: "working"}
trackEvent(){
this.EMMA.trackEvent(this.eventToken);
}
To register and/or log in you need to send the user id in the app (Customer ID):
EMMA.registerUser({
userId:"emma",
email:"email.prueba@emma.io"
});
EMMA.loginUser({
userId:"emma",
email:"email@emma.io"
});
EMMA allows the sending of key/value properties associated with the device:
trackUserExtraInfo(){
this.EMMA.trackUserExtraInfo({TAG : "EMMA_EXAMPLE"});
}
To measure the user's location add the following method:
EMMA.trackLocation();
The user's location will only be collected once at login.
The purchase process consists of several methods: startOrder, addProduct and trackOrder.
EMMA.startOrder({
orderId: "EMMA",
totalPrice: 100,
customerId: "EMMA",
//opcionales
coupon: "coupon",
extras: {IONIC: "Working"}
});
EMMA.addProduct({
productId: "SDK",
productName: "SDK",
quantity: 1,
price: 1,
extras: {IONIC: "Working"}
});
EMMA.trackOrder();
In the case of cancelling a purchase that has already been made, use the cancelOrder method.
EMMA.cancelOrder();
EMMA includes 5 different communication formats that you can integrate to impact your users:
Banner format is only supported on Android.
EMMA's NativeAds allow you to integrate personalised advertising that adapts to the design of your application. Unlike other formats (StartView, AdBall, etc.), you have complete control over how the content is displayed. EMMA provides the data (title, image, CTA, etc.) configured in the EMMA dashboard, and your app decides how to display it.
Before requesting a NativeAd, you must:
For more details on how to configure a NativeAd in the dashboard, please refer to our main documentation.
Returns a single NativeAd in a single-element array.
EMMA.inAppMessage({
type: EMMA.inAppTypes.NATIVEAD,
templateId: 'templateId',
batch: false, // or do not specify (default value)
inAppResponse: (nativeAds: EMMANativeAd[]) => {
if (nativeAds.length > 0) {
const nativeAd = nativeAds[0];
// Process the NativeAd
}
}
});
Returns an array with all the NativeAds available for the template.
EMMA.inAppMessage({
type: EMMA.inAppTypes.NATIVEAD,
templateId: 'templateId',
batch: true,
inAppResponse: (nativeAds: EMMANativeAd[]) => {
nativeAds.forEach((nativeAd) => {
// Process each NativeAd
});
}
});
It should be sent when the NativeAd is displayed to the user.
EMMA.sendInAppImpression(EMMA.inAppTypes.NATIVEAD, nativeAd.id);
openNativeAd() opens the CTA and automatically handles click tracking. There is no need to call sendInAppClick().
EMMA.openNativeAd(nativeAd.id, nativeAd.cta, nativeAd.showOn);
If you need to track the click without opening the CTA.
EMMA.sendInAppClick(EMMA.inAppTypes.NATIVEAD, nativeAd.id);
It should be sent when the user closes or dismisses the NativeAd without interacting with it.
EMMA.sendInAppDismissedClick(EMMA.inAppTypes.NATIVEAD, nativeAd.id);
Example of a data model for receiving the object returned in the NativeAd response.
interface Fields {
Subtitle: string;
CTA: string;
"Main picture": string;
Title: string;
}
interface EMMANativeAd {
id: number; // Campaign ID
templateId: string; // ID of the template used
cta: string; // CTA URL
times: number; // Number of times displayed
tag: string | null; // Associated tag
showOn: string; // "browser" | "inapp" -> where to open the CTA
fields: Fields; // Custom fields in the template
}
// Request multiple NativeAds
EMMA.inAppMessage({
type: EMMA.inAppTypes.NATIVEAD,
templateId: 'templateId',
batch: true,
inAppResponse: (nativeAds: EMMANativeAd[]) => {
nativeAds.forEach((nativeAd) => {
// Display NativeAd in UI
displayNativeAd(nativeAd);
// Send impression when displayed
EMMA.sendInAppImpression(EMMA.inAppTypes.NATIVEAD, nativeAd.id);
});
}
});
// Manage user interactions
// When you click on the CTA
function onNativeAdClick(nativeAd: EMMANativeAd) {
EMMA.openNativeAd(nativeAd.id, nativeAd.cta, nativeAd.showOn);
}
// When closing without interacting
function onNativeAdDismiss(nativeAd: EMMANativeAd) {
EMMA.sendInAppDismissedClick(EMMA.inAppTypes.NATIVEAD, nativeAd.id);
}
Any format other than NativeAd does not expect an explicit result, as it is automatically injected into the view. Example of use:
EMMA.inAppMessage({ type });
console.log(`InApp ${type} message`);
The Adball, Banner, Startview and Strip formats, when injected, send impression and click events automatically when these actions are performed.
In order to control the use of the data protection law EMMA provides several methods to activate/deactivate the tracking of users.
// Enable user tracking
EMMA.enableUserTracking();
//Disable user tracking
EMMA.disableUserTracking(false);
The disableUserTracking method provides a flag to permanently remove the user in case tracking is disabled. Note that this action is irreversible and all data associated with the user will be lost.
To check if tracking is enabled or disabled use the following method:
const isEnabled = EMMA.isUserTrackingEnabled();
If the app does not use login/registration events to notify the customerId you can send it with the following method:
EMMA.setCustomerId(customerId);
Manually sets the user's preferred language.
This method allows overwriting the default language of the device to set a custom language to be used in all SDK requests. This is useful in applications that allow the user to select a different language than the one configured on the device.
The language code in ISO 639-1 format must be used: es (Spanish), en (English), fr (French), de (German), it (Italian), zh-Hans (Simplified Chinese), zh-Hant (Traditional Chinese), etc.
// In this case, it establishes English as the language
EMMA.setUserLanguage("en");
If this method is not called, EMMA will default to the user's preferred language configured in the device system.
In case the push methods of the EMMA SDK are not used, the push token can be sent to send push notifications. In case the SDK methods are added, this method is not necessary.
EMMA.sendPushToken(token);
To request the IDFA identifier use the following method:
EMMA.requestTrackingWithIdfa();
Since Android 13 to receive notifications it is necessary to request permission from the user. As of version 1.3.0 the following method for requesting permission has been added:
EMMA.requestNotificationPermission();