Add the Cordova SDK to your app

Overview

You can implement Acoustic mobile app messaging in your Cordova projects for iOS and Android apps using our Cordova SDK.

🚧

WARNING:

When Acoustic Mobile App Messaging stores data that you send, the data is not encrypted; therefore, it is recommended that you do not transmit sensitive information in the inbox, in-app, and mobile app messages. The data is not encrypted in our databases or log files or when stored on the device. If you must transmit sensitive information, encrypt the data before sending it and decrypt the data in memory on the device.

Before you begin

• Download the Cordova plug-in. You must create a Cordova project with the plug-in before you begin using your Cordova-enabled app.
• Download the Cordova package. Verify that you have the appropriate environment. For more information, see supported platforms.
• Install TypeScript compiler version 3 or later. Run npm install typscript to install the TypeScript compiler.

Prepare the plug-ins

We’ve historically deployed our Cordova SDK with JS files already generated in the ZIP file package. We upgraded Cordova SDK version 3.8.4 to use TypeScript to provide you with more flexibility. You can now generate the JS files using the Typescript compiler version 3 or later by running the build.sh command.

Typescript is a language for application-scale JavaScript. It provides developers with auto-complete, IntelliSense capabilities, and supports a tighter integration with your code editor. TypeScript compiles to readable, standards-based JavaScript. For more information, see TypeScript.

If you have an existing project that uses the TypeScript compiler or if you intend to use the TypeScript compiler for a new project, then check the SDK TS config files in each plug-in directory to ensure that all your plug-ins are in the same directory.

📘

Note:

If you have highly customized configurations to your build environments, you may need to change the TS config files accordingly.

Create a Cordova application

1. Cordova creates an example app called com.app.id Example App. You must replace com.app.id with your Apple app ID. For example,

$ cordova create destination_folder com.acoustic.mobilepush Example

2. Change the project folder and add the iOS and Android platforms to the app.
   For example,

$ cd destination_folder
$ cordova platform add [email protected] 
$ cordova platform add ios

Verify Cordova plug-in exists in your project

Verify if the Cordova plug-ins exist in your project, and if a plug-in does not exist, add the plug-in.

📘

Note:

Starting in Cordova SDK version 3.4.3 (and later), you are not required to add the google.playservices plug-in before you install the Acoustic Mobile App Messaging SDK.

Add the plug-ins

To use mobile app messaging with Cordova apps, add the following plug-ins:

📘

Note:

Ensure that you have built the plugins first before you add the plug-ins to your project. For more information, see Prepare the plug-ins

Add the Cordova plug-in

Add the Cordova plug-in by using the syntax in the Cordova plug-in syntax examples. Ensure that you replace the path-to-mce-cordova-sdk with the path for the Acoustic Mobile App Messaging SDK.
The following variables are required:

• ANDROID_APPKEY – Specify the app key generated from Acoustic Campaign. Do not change the app key after you publish your app.
• IOS_DEV_APPKEY and IOS_PROD_APPKEY – Specify the development app keys and production app keys generated in Campaign. Depending on how the app is compiled, the SDK can choose the correct app key to use. Do not change your app key after you publish your app.

The following variables are optional. If you do not include an optional variable in the command line, the default value is used.

• AUTO_INITIALIZE – Tells the SDK to start immediately when the application is started. You usually want the auto_initialize, but sometimes it’s useful to hold off starting the SDK (with its associated requests for permissions) until after you have had a chance to notify or authenticate the user.
• LOGLEVEL – Sets the loglevel for debugging output messages. The default value is error. For more information, see Config settings.
• SERVER_URL – Sets the SERVER_URL for your pod. The default value is https://mobile-sdk-lib-XX-Y.brilliantcollector.com.

📘

Note:

You will need to update your baseUrl to the one supplied to you. For information about SERVER_URLs for your pod, see Setting the baseURL.

• INVALIDATE_EXISTING_USER – Sets the non-sticky MUID option. If set to true, new MUIDs are assigned to devices when apps are uninstalled and then reinstalled. The default value is false. For more information, see Assign new MUIDs.
• AUTO_REINITIALIZE – Sets the Auto Reinitialize option that determines the plug-in’s behavior when the GDPR state is true. The default value is true. For more information, see Re-initialize the SDK after a GDPR request for erasure.

Cordova plug-in syntax example:

$ cordova plugin add ./path-to-mce-cordova-sdk/plugins/co.acoustic.mobile.push.sdk \
 --variable ANDROID_APPKEY=gcXXXX \
 --variable IOS_DEV_APPKEY=apXXXXXX \
 --variable IOS_PROD_APPKEY=apXXXXX \
 --variable SERVER_URL=https://mobile-sdk-lib-XX-Y.brilliantcollector.com \
 --variable AUTO_INITIALIZE=true \
 --variable LOGLEVEL=verbose \
 --variable AUTO_INITIALIZE_LOCATION=true \
 --variable INVALIDATE_EXISTING_USER=true \
 --variable AUTO_REINITIALIZE=false \
 --variable CHANNEL_NAME="The name of the channel as it appears in the Notifications system dialog. This is required for Android 8 and higher." \
 --variable CHANNEL_DESCRIPTION="The description of the channel as it appears in the Notifications system dialog. This is required for Android 8 and higher." \
 --variable CHANNEL_ID="The ID (string) used to identify notifications as being sent to the SDK. Only one ID may be used for all SDK messages. This is required for Android 8 and higher."

Add support for FCM

$ cordova plugin add ./path-to-mce-cordova-sdk/plugins/co.acoustic.mobile.push.plugin.fcm

After adding the plug-in, to enable FCM support, place your google-services.json file in Project’s main directory.

Add the call plug-in

If the app uses the built-in dial action, the Android app will need dial permission. You can add it as follows:

$ cordova plugin add ./path-to-mce-cordova-sdk/plugins/co.acoustic.mobile.push.plugin.dial

Add the location plug-in

If you want to use geofences or beacons with Cordova apps, add the location plug-in for Cordova. For more information, see Device Location Awareness (DLA).

The following variables are optional. If you do not include optional variables in the command line, the default value is used.

• SYNC_RADIUS – Sets the radius of the reference area for geofences. The default is 100000 m.
• SYNC_INTERVAL – Sets the time interval between reference area geofence and beacon synchronizations with the server. The default is 600 seconds.
• AUTO_INITIALIZE_LOCATION – Starts location services and monitoring for locations. The default is true.

Add geofence example:

$ cordova plugin add ./path-to-mce-cordova-sdk/plugins/co.acoustic.mobile.push.plugin.location
 --variable SYNC_RADIUS=10000 --variable SYNC_INTERVAL=60

Add beacon example:

$ cordova plugin add ./path-to-mce-cordova-sdk/plugins/co.acoustic.mobile.push.plugin.beacon
 --variable UUID=your_beacon_UUID

Set up your iOS project

Dark mode support on iOS

Run the image replacer at app startup to handle dark mode support on iOS.

document.addEventListener('deviceready', function() {
    MCEPlugin.replaceImages();
    window.matchMedia("(prefers-color-scheme: dark)").addListener(e => e.matches && MCEPlugin.replaceImages())
    window.matchMedia("(prefers-color-scheme: light)").addListener(e => e.matches && MCEPlugin.replaceImages())
}

Prepare the project

Run the prepare command.

$ cordova prepare

Add push capabilities to your iOS project

1. Open the .xcworkspace file in platforms/ios/{project_name}.xcworkspace.
2. Select your project in Xcode | Capabilities and verify that Push Notification is enabled (On).

📘

Note:

If you do not set your team and provisioning profile, the app does not have permission to get the APNs deviceToken.

Add the Notification Service Framework to your app

This framework should be added to your project if you have requirements for:

• dynamic action categories
• media attachments
• other mutable-content support
  For more information, see Add the iOS Notification service framework to your Cordova project.

Set up your Android project

📘

Note:

If you migrate the Cordova build from an earlier release to one later than 3.5.0, you must make the changes described in Migrating the Android SDK to release 3.7.1.0.2 (or later).

1. Edit the AndroidManifest.xml file.
2. Verify that the segment of your AndroidManifest.xml contains the following entry.

android:name="co.acoustic.mobile.push.sdk.js.MceJsonApplication"

3. If segment does not contain the entry, add the entry manually. For example,

<application android:hardwareAccelerated="true"
android:icon="@drawable/icon"
android:label="@string/app_name"
android:name="co.acoustic.mobile.push.sdk.js.MceJsonApplication"
android:supportsRtl="true">

4. If you want to use the drawable resource instead of the Cordova default mipmap, modify the node of the AndroidManifest.xml file after you install the Cordova plug-in. For example,

<application
android:hardwareAccelerated="true"
android:icon="@mipmap/icon" <--- change to "@drawable/icon" if desired
android:label="@string/app_name"
android:name="co.acoustic.mobile.push.sdk.js.MceJsonApplication"
android:supportsRtl="true" />

5. Ensure that you set the ANDROID_HOME variable. For example,

$ export ANDROID_HOME=/Applications/android

Update icons on a push notification

In your Cordova Android app, the icons on a push notification are provided by default. You can change or update these icons using the following method:

MCEPlugin.setIcon('logo');

Where 'logo' is the image file logo.png from your Android drawable resources.

Test your Apache Cordova iOS and Android apps

1. Build and run your Android app and iOS app.

$ cordova run android # build and run .apk on an android device
$ cordova emulate android # build and run on an emulator

2. Run the emulator for your sample apps.
3. Ensure that the app registers and receives the userId. You can either check the console log or the Acoustic Campaign console for the registered mobile user ID.
4. Send notifications to the iOS and Android apps and confirm that the devices receive the notification.

When the plug-in is installed, and the config.xml file is filled out, the application automatically registers with the push provider servers and the MCE servers. You can start using the APIs that send bulk mobile app messages immediately with no changes to support the standard actions available.

📘

Note:

Use the MCEPlugin.getRegistrationDetails callback to get the user ID and channel ID values; if you keep a copy of them in your systems. The callback includes an object with user ID and channel ID keys. If the system did not register with the servers, you could instead use the MCEPlugin.setRegistrationCallback callback, which is called only once when the registration happens.