@adobe/react-native-aepmessaging is a wrapper around the iOS and Android Adobe Journey Optimizer Messaging extension to allow for integration with React Native applications.
The messaging extension has the following peer dependenices, which must be installed prior to installing the messaging extension:
See Requirements and Installation instructions on the main page
Install the @adobe/react-native-aepmessaging package:
NPM:
npm install @adobe/react-native-aepmessagingYarn:
yarn add @adobe/react-native-aepmessagingTo initialize the SDK, use the following methods:
Refer to the root Readme for more information about the SDK setup.
import {
Messaging,
MessagingDelegate,
MessagingEdgeEventType,
Message
} from '@adobe/react-native-aepmessaging';Returns the version of the AEPMessaging extension
Syntax
extensionVersion(): Promise<string>Example
Messaging.extensionVersion().then((version) =>
console.log('AdobeExperienceSDK: Messaging version: ' + version)
);To configure Adobe Journey Optimizer Messaging in Launch follow the steps in Configure Adobe Journey Optimizer
Handling push notifications must be done in native (Android/iOS) code for the React Native app. To configure push notifications in the native project, follow the instructions provided for their respective platforms:
The AEPMessaging extension's push messaging APIs must be called from the native Android/iOS project of React Native app.
In Android, MessagingPushPayload can be used for getting the notification attributes like title, body, and action. These are useful for push notification creation.
Initiates a network call to retrieve remote in-app message definitions.
Syntax
refreshInAppMessages();Example
Messaging.refreshInAppMessages();Sets a custom MessagingDelegate in AEPCore to listen for Message lifecycle events.
Syntax
setMessagingDelegate(delegate: MessagingDelegate)Example
const messagingDelegate = {
onShow(message: Message) {
// Action after message is displayed.
},
onDismiss(message: Message) {
// Action after message is dismissed.
},
shouldShowMessage(message: Message) {
return true; //Return true to show the Message else return false
},
urlLoaded(url: string, message: Message) {
// Action after message loads an URL
}
};
Messaging.setMessagingDelegate(messagingDelegate);Example
const messagingDelegate = {
shouldShowMessage(message: Message) {
Messaging.saveMessage(message);
return false;
}
};Dispatches an event to fetch propositions for the provided surfaces from remote.
Syntax
updatePropositionsForSurfaces(surfaces: string[])Example
Messaging.updatePropositionsForSurfaces(['mobileapp://my-surface']);Retrieves the previously fetched (and cached) feeds content from the SDK for the provided surfaces. If the feeds content for one or more surfaces isn't previously cached in the SDK, it will not be retrieved from Adobe Journey Optimizer via the Experience Edge network. This can be used in order to retrieve code based experiences, content cards and other proposition types.
Syntax
getPropositionsForSurfaces(surfaces: string[])Example
const propositions = Messaging.getPropositionsForSurfaces(['my-surface']);
console.log(propositions);Once propositions have been retrieved, their items will be typed to allow you to easily figure out what type they are using their schema property
for (let item in proposition.items) {
if (item.schema === PersonalizationSchema.CONTENT_CARD) {
// Proposition Item is a content card, and will be fully typed
console.log(item.data.content);
}
}A unified tracking API is available for any proposition item (Content Cards, HTML, JSON, code-based items). You can use the same track() method regardless of content type, making your code more consistent and maintainable.
Syntax
// Track display event
propositionItem.track(MessagingEdgeEventType.DISPLAY);
// Track interaction with custom data + event + optional tokens
propositionItem.track(
interaction /* string | null */,
MessagingEdgeEventType.INTERACT /* enum value */,
[/* tokens */] /* string[] | null */
);When using getPropositionsForSurfaces, the returned objects are already MessagingProposition instances with typed items and convenient tracking via PropositionItem.track(...).
import { Messaging, MessagingProposition, MessagingEdgeEventType } from '@adobe/react-native-aepmessaging';
const SURFACES = ['mobileapp://my-surface'];
const messages = await Messaging.getPropositionsForSurfaces(SURFACES);
for (const surface of SURFACES) {
const propositions = messages[surface] || [];
for (const proposition of propositions) {
for (const propositionItem of proposition.items) {
// Track interaction with custom data
propositionItem.track('content_card_clicked', MessagingEdgeEventType.INTERACT, null);
// Track with tokens for sub-item tracking
propositionItem.track('button_click', MessagingEdgeEventType.INTERACT, ['token-1', 'token-2']);
}
}
}Retrieves the most recently displayed message object
Syntax
Messaging.getLatestMessage();Example
const message = Messaging.getLatestMessage();
console.log(message.id);Retrieves a list of all messages that have been cached in-memory
Syntax
Messaging.getCachedMessages();Example
const messages = Messaging.getCachedMessages();
messages.forEach((message) => message.clear());Allows setting a global setting for shouldSaveMessage and shouldShowMessage. Use a messaging delegate defined in the setMessagingDelegate method for more fine-grained control of message settings
Syntax
Messaging.setMessageSettings(shouldShowMessage: boolean, shouldSaveMessage: boolean)Example
Messaging.setMessageSettings(true, false);The Message object passed to the MessagingDelegate contains the following functions to handle a message:
Signals to the UIService that the message should be shown.
Syntax
show();Example
var message: Message;
message.show();Signals to the UIService that the message should be dismissed.
Syntax
dismiss(((suppressAutoTrack: ?boolean) = false))Example
var message: Message;
message.dismiss(true);Generates an Edge Event for the provided interaction and event type.
Syntax
track(interaction: ?string, eventType: MessagingEdgeEventType)Example
var message: Message;
message.track('sample text', MessagingEdgeEventType.IN_APP_DISMISS);Enables/Disables autotracking for message events.
Syntax
setAutoTrack(autoTrack: boolean)Example
var message: Message;
message.setAutoTrack(true);Clears the reference to the in-memory cached Message object. This function must be called if a message was saved by calling Messaging.saveMessage but no longer needed. Failure to call this function leads to memory leaks.
Syntax
clear();Example
var message: Message;
message.clear();Registers a javascript interface for the provided handler name to the WebView associated with the InAppMessage presentation to handle Javascript messages. When the registered handlers are executed via the HTML the result will be passed back to the associated handler.
Syntax
handleJavascriptMessage(handlerName: string, handler: (content: string) => void);Example
It can be used for the native handling of JavaScript events. Please refer to the tutorial for more information.
App developers can now create a type MessagingDelegate in order to be alerted when specific events occur during the lifecycle of an in-app message.
Definition of type MessagingDelegate is:
type MessagingDelegate = {
onShow(message: Message): void,
onDismiss(message: Message): void,
shouldShowMessage(message: Message): boolean,
urlLoaded(url: string, message: Message): void, // iOS Only
onContentLoaded(message: Message): void // Android Only
};Objects of type MessagingDelegate can be created as shown below:
const messagingDelegate = {
onShow(message: Message) {
// Action after message is displayed.
},
onDismiss(message: Message) {
// Action after message is dismissed.
},
shouldShowMessage(message: Message) {
return true; //Return true to show the Message else return false
},
urlLoaded(url: string, message: Message) {
// Action after message loads an URL
},
onContentLoaded(message: Message) {
// Action after message loads content
}
};If a MessagingDelegate has been set, the delegate's shouldShowMessage function will be called prior to displaying an in-app message for which the end user has qualified. The developer is responsible for returning true if the message should be shown, or false if the message should be suppressed.
Below is an example of when the developer may choose to suppress an in-app message due to the status of some other workflow within the app:
function shouldShowMessage(message: Message): boolean {
if (someOtherWorkflowStatus == 'inProgress') {
return false;
}
return true;
}Another option for the developer is to store a reference to the Message object, and call the show function on it at a later time. To use this functionality, app developers can call Messaging.saveMessage(message) from the shouldShowMessage of the MessagingDelegate for caching the Message on the native side of the RN AEPMessaging package.
Continuing with the above example, the developer has stored the message that was triggered initially, and chooses to show it upon completion of the other workflow:
var cachedMessage: Message;
function otherWorkflowFinished() {
anotherWorkflowStatus = 'complete';
cachedMessage.show();
}
function shouldShowMessage(message: Message): boolean {
if (anotherWorkflowStatus === 'inProgress') {
// store the current message for later use
Messaging.saveMessage(message);
cachedMessage = message;
return false;
}
return true;
}Important: If the cached message is no longer needed after being used, free up the references to the Message object by calling message.clearMessage() to prevent memory leaks. In above example after displaying the in app message using cached message object if it is no longer needed then it should be cleared as shown below.
function otherWorkflowFinished() {
anotherWorkflowStatus = 'complete';
currentMessage.show();
currentMessage.clearMessage();
}Deprecated in 7.2.0: Use Proposition.track(...) instead. This API will be removed in a future release.
Tracks a Display interaction with the given ContentCard
Syntax
Messaging.trackContentCardDisplay(proposition, contentCard);Deprecated in 7.2.0: Use Proposition.track(...) instead. This API will be removed in a future release.
Tracks a Click interaction with the given ContentCard
Syntax
Messaging.trackContentCardInteraction(proposition, contentCard);