capacitor-marketingcloud

MarketingCloud Capacitor Plugin

Install

npm install @okode/capacitor-marketingcloud
npx cap sync

Publish

Ensure you are athenticated in NPM.js using npm login

npm ci
npm run build
npm version [VERSION] -m "Bumped version %s [ci skip]"
git tag [VERSION]
git push
git push --tags
npm publish --access public

Previous steps

This plugin is built to be used along side with the official Capacitor Push Notifications plugin. Therefore, first of all, you must configure your project following the plugin instructions. This implementation approach avoid us to reimplement all logic that this official plugin already implements. For example, the developer will have to request the permission for push notifications by using Push Notifications plugin API.

iOS

Initialize SFMC in the application(:didFinishLaunchingWithOptions) method of your AppDelegate.swift. Example:

func application(_ application: UIApplication,
  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
  let appId = "APP_ID"
  let token = "TOKEN"
  let serverUrl = "SERVER_URL"
  let isAnalyticsEnabled = true // true | false
  MarketingCloud.initialize(appId, token, serverUrl, isAnalyticsEnabled)
  return true
}

Send push token to SFMC in the application(:didRegisterForRemoteNotificationsWithDeviceToken) method of your AppDelegate.swift. Example:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  NotificationCenter.default.post(name: .capacitorDidRegisterForRemoteNotifications, object: deviceToken) // Documented in Capacitor Push Notifications plugin integration
  MarketingCloud.setPushToken(deviceToken)
}

Note: check the official Marketing Cloud SDK documentation to know how to get the configuration values.

Android

Initialize SFMC in the onCreate method of your Android application class. If you don't have one, create it and reference it in your AndroidManifest.xml. Example:

public class MyApp extends Application {

  @Override
  public void onCreate() {
    super.onCreate();
    String appId = "APP_ID";
    String token = "TOKEN";
    String serverUrl = "SERVER_URL";
    boolean isAnalyticsEnabled = true; // true | false
    MarketingCloud.Companion.initialize(
      getApplicationContext(),
      appId,
      token,
      serverUrl,
      isAnalyticsEnabled,
      initializationStatus -> Unit.INSTANCE
    );
  }

}

Note: check the official Marketing Cloud SDK documentation to know how to get the configuration values.

Implement your custom FirebaseMessagingService to send push token to SFMC and also handling SFMC push notifications with the plugin. Example:

public class MyAppFirebaseMessagingService extends FirebaseMessagingService {

  @Override
  public void onNewToken(String newToken) {
    super.onNewToken(newToken);
    MarketingCloud.Companion.setPushToken(newToken);
    PushNotificationsPlugin.onNewToken(newToken);
  }

  @Override
  public void onMessageReceived(RemoteMessage remoteMessage) {
    super.onMessageReceived(remoteMessage);
    if (MarketingCloud.Companion.isMarketingCloudNotification(remoteMessage)) {
      MarketingCloud.Companion.showNotification(remoteMessage, res -> Unit.INSTANCE);
    } else {
      // Handle any notification sent from other notifications broker
    }
    PushNotificationsPlugin.sendRemoteMessage(remoteMessage);
  }

}

And register it in your AndroidManifest.xml. Example:

  <application...>
    ...
    <service android:name="com.okode.myapp.MyAppFirebaseMessagingService" android:stopWithTask="false">
      <intent-filter android:priority="9999">
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
      </intent-filter>
    </service>
    ...
  </application>

Notification icon

Configure your notification icon by setting the resource name in your strings.xml:

<?xml version='1.0' encoding='utf-8'?>
<resources>
  ...
  <string name="sfmcplugin_notification_icon">ic_notification</string>
  ...
</resources>

Default notification channel for Android O+

Configure the default notification channel for Android 0+ devices by setting this in your strings.xml:

<?xml version='1.0' encoding='utf-8'?>
<resources>
  ...
  <string name="sfmcplugin_default_notification_channel_id">my_channel_id</string>
  ...
</resources>

Note: this plugin will use the default SFMC SDK channel if you don't set a custom one. So, only set it up if you needed.

API

• isPushEnabled()
• setPushEnabled(...)
• getProfileId()
• setProfileId(...)
• getAttributes()
• setAttribute(...)
• clearAttribute(...)
• getTags()
• addTag(...)
• removeTag(...)
• isMarketingCloudNotification(...)
• notifyNotificationOpened(...)
• showNotification(...)
• addListener('notificationOpened', ...)
• Interfaces

isPushEnabled()

isPushEnabled() => Promise<{ value: boolean; }>

Returns true if push notifications are enabled, otherwise false.

Returns: Promise<{ value: boolean; }>

Since: 1.0.0

---

setPushEnabled(...)

setPushEnabled(opts: { enabled: boolean; }) => void

Sets push notifications status according to the provided input param.

Param	Type
opts	{ enabled: boolean; }

Since: 1.0.0

---

getProfileId()

getProfileId() => Promise<{ value: string; }>

Get profile id.

Returns: Promise<{ value: string; }>

Since: 1.0.0

---

setProfileId(...)

setProfileId(opts: { value: string; }) => void

Set profile id.

Param	Type
opts	{ value: string; }

Since: 1.0.0

---

getAttributes()

getAttributes() => Promise<{ attributes: string; }>

Gets attributes.

Returns: Promise<{ attributes: string; }>

Since: 1.0.0

---

setAttribute(...)

setAttribute(opts: { key: string; value: string; }) => void

Sets an attribute.

Param	Type
opts	{ key: string; value: string; }

Since: 1.0.0

---

clearAttribute(...)

clearAttribute(opts: { key: string; }) => Promise<{ value: boolean; }>

Clears an attribute.

Param	Type
opts	{ key: string; }

Returns: Promise<{ value: boolean; }>

Since: 1.0.0

---

getTags()

getTags() => Promise<{ tags: string[]; }>

Gets tags.

Returns: Promise<{ tags: string[]; }>

Since: 1.0.0

---

addTag(...)

addTag(opts: { value: string; }) => Promise<{ value: boolean; }>

Adds a tag.

Param	Type
opts	{ value: string; }

Returns: Promise<{ value: boolean; }>

Since: 1.0.0

---

removeTag(...)

removeTag(opts: { value: string; }) => Promise<{ value: boolean; }>

Removes a tag.

Param	Type
opts	{ value: string; }

Returns: Promise<{ value: boolean; }>

Since: 1.0.0

---

isMarketingCloudNotification(...)

isMarketingCloudNotification(opts: { notification: any; }) => Promise<{ value: boolean; }>

Helper method to identify a push message payload sent from the Marketing Cloud.

Param	Type
opts	{ notification: any; }

Returns: Promise<{ value: boolean; }>

Since: 1.0.0

---

notifyNotificationOpened(...)

notifyNotificationOpened(opts: { notification: any; }) => void

Helper method to notify SFMC that your notification has been opened. When this method is called providing a valid SFMC notificaion then 'notificationOpened' listener is fired.

Only available on iOS.

Param	Type
opts	{ notification: any; }

Since: 1.0.0

---

showNotification(...)

showNotification(opts: { notification: any; }) => Promise<{ value: boolean; }>

Shows a SFMC notification. If the method returns false, that means that the provided notification payload is not a valid SFMC one and it could be handled successfully.

Only available on Android.

Param	Type
opts	{ notification: any; }

Returns: Promise<{ value: boolean; }>

Since: 1.0.0

---

addListener('notificationOpened', ...)

addListener(eventName: 'notificationOpened', listenerFunc: (notification: MarketingCloudNotification) => void) => PluginListenerHandle

Called when a SFMC notification is opened.

Provides the notification opened.

Param	Type
eventName	'notificationOpened'
listenerFunc	(notification: MarketingCloudNotification) => void

Returns: PluginListenerHandle

Since: 1.0.0

---

Interfaces

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

MarketingCloudNotification

Prop	Type
sfmcMessageId	string
extras	any
action	'tap'