Migrate from v5 to v6
This guide will help you migrate Amplify JavaScript v5's In-App Messaging APIs to the new v6's In-App Messaging APIs.
Initialization
As of v6 of Amplify, In-App Messaging must first be initialized by using the initializeInAppMessaging
API exported from the aws-amplify/in-app-messaging
path. In a typical application, this step should be performed immediately after Amplify is configured.
1import { Amplify } from 'aws-amplify';2import amplifyconfig from './amplifyconfiguration.json';3import { initializeInAppMessaging } from 'aws-amplify/in-app-messaging';4
5Amplify.configure(amplifyconfig);6initializeInAppMessaging();
InAppMessaging.syncMessages
The syncMessages
API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/in-app-messaging
path.
1import { syncMessages } from 'aws-amplify/in-app-messaging';2
3await syncMessages();
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4await InAppMessaging.syncMessages();
Displaying messages
The way in-app messages are displayed in v6 has not changed in behavior. You will continue to use the record
API from Analytics or the dispatchEvent
API from In-App Messaging. However, these APIs are now exported from the aws-amplify/analytics
and aws-amplify/in-app-messaging
paths, respectively.
Analytics.record
1import { record } from 'aws-amplify/analytics';2
3const event = {4 name: 'first_event',5 attributes: { color: 'red' },6 metrics: { quantity: 10 }7};8
9record(event);
1import { Analytics } from 'aws-amplify';2
3const event = {4 name: 'first_event',5 attributes: { color: 'red' },6 metrics: { quantity: 10 }7};8
9Analytics.record(event);
InAppMessaging.dispatchEvent
1import { dispatchEvent } from 'aws-amplify/in-app-messaging';2
3const event = {4 name: 'first_event',5 attributes: { color: 'red' },6 metrics: { quantity: 10 }7};8
9dispatchEvent(event);
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const event = {5 name: 'first_event',6 attributes: { color: 'red' },7 metrics: { quantity: 10 }8};9
10InAppMessaging.dispatchEvent(event);
InAppMessaging.clearMessages
The clearMessages
API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/in-app-messaging
path.
1import { clearMessages } from 'aws-amplify/in-app-messaging';2
3await clearMessages();
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4await InAppMessaging.clearMessages();
InAppMessaging.identifyUser
The identifyUser
API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/in-app-messaging
path. Additionally, the input parameters have been updated as follows:
- Instead of two position positional parameters (corresponding to
userId
anduserInfo
), there are now three named parameters:userId
,userProfile
andoptions
(i.e. a single input object containing these properties). - The
attributes
property previously found underuserInfo
has been renamed tocustomProperties
and can now be found underuserProfile
. - A new
userAttributes
property can be found underoptions
. - New convenience properties
name
,email
andplan
can be found underuserProfile
. These properties are automatically merged intocustomProperties
.
Input
V5
1userId: string;2userInfo: {3 attributes?: Record<string, string[]>;4 demographic?: {5 appVersion?: string;6 locale?: string;7 make?: string;8 model?: string;9 modelVersion?: string;10 platform?: string;11 platformVersion?: string;12 timezone?: string;13 };14 location?: {15 city?: string;16 country?: string;17 latitude?: number;18 longitude?: number;19 postalCode?: string;20 region?: string;21 };22 metrics?: Record<string, number>;23}
V6
1input: {2 userId: string;3 userProfile: {4 customProperties?: Record<string, string[]>;5 demographic?: {6 appVersion?: string;7 locale?: string;8 make?: string;9 model?: string;10 modelVersion?: string;11 platform?: string;12 platformVersion?: string;13 timezone?: string;14 };15 email?: string;16 location?: {17 city?: string;18 country?: string;19 latitude?: number;20 longitude?: number;21 postalCode?: string;22 region?: string;23 };24 metrics?: Record<string, number>;25 name?: string;26 plan?: string;27 };28 options?: { userAttributes?: Record<string, string[]>; };29}
1import { identifyUser } from 'aws-amplify/in-app-messaging';2
3const identifyUserInput = {4 userId: 'user-id',5 userProfile: {6 email: 'example@service.com',7 name: 'User A',8 plan: 'Standard'9 customProperties: {10 hobbies: ['cooking', 'knitting'],11 },12 demographic: {13 appVersion: '1.0.0',14 locale: 'en_US',15 make: 'Apple',16 model: 'iPhone',17 modelVersion: '13',18 platform: 'iOS',19 platformVersion: '15',20 timezone: 'Americas/Los_Angeles'21 },22 location: {23 city: 'Seattle',24 country: 'US',25 postalCode: '98121',26 region: 'WA',27 latitude: 0.0,28 longitude: 0.029 },30 metrics: {31 logins: 15732 },33 },34};35
36await identifyUser(identifyUserInput);
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const userId = 'user-id';5const userInfo = {6 address: 'example@service.com',7 attributes: {8 hobbies: ['cooking', 'knitting'],9 },10 demographic: {11 appVersion: '1.0.0',12 locale: 'en_US',13 make: 'Apple',14 model: 'iPhone',15 modelVersion: '13',16 platform: 'iOS',17 platformVersion: '15',18 timezone: 'Americas/Los_Angeles'19 },20 location: {21 city: 'Seattle',22 country: 'US',23 postalCode: '98121',24 region: 'WA',25 latitude: 0.0,26 longitude: 0.027 },28 metrics: {29 logins: 15730 },31 optOut: 'NONE'32};33
34await InAppMessaging.identifyUser(userId, userInfo);
Responding to interaction events
The ways to respond to your users' interactions with in-app messages in v6 have not changed in behavior. You will continue to use the onMessageReceived
, onMessageDisplayed
, onMessageDismissed
and onMessageActionTaken
APIs to respond to interaction events. However, these APIs are now exported from the aws-amplify/in-app-messaging
path.
InAppMessaging.onMessageReceived
1import { onMessageReceived } from 'aws-amplify/in-app-messaging';2
3const myMessageReceivedHandler = (message) => {4 // Do something with the received message5};6
7const listener = onMessageReceived(myMessageReceivedHandler);8
9listener.remove(); // Remember to remove the listener when it is no longer needed
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const myMessageReceivedHandler = (message) => {5 // Do something with the received message6};7
8const listener = InAppMessaging.onMessageReceived(myMessageReceivedHandler);9
10listener.remove(); // Remember to remove the listener when it is no longer needed
InAppMessaging.onMessageDisplayed
1import { onMessageDisplayed } from 'aws-amplify/in-app-messaging';2
3const myMessageDisplayedHandler = (message) => {4 // Do something with the displayed message5};6
7const listener = onMessageDisplayed(myMessageDisplayedHandler);8
9listener.remove(); // Remember to remove the listener when it is no longer needed
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const myMessageDisplayedHandler = (message) => {5 // Do something with the displayed message6};7
8const listener = InAppMessaging.onMessageDisplayed(myMessageDisplayedHandler);9
10listener.remove(); // Remember to remove the listener when it is no longer needed
InAppMessaging.onMessageDismissed
1import { onMessageDismissed } from 'aws-amplify/in-app-messaging';2
3const myMessageDismissedHandler = (message) => {4 // Do something with the dismissed message5};6
7const listener = onMessageDismissed(myMessageDismissedHandler);8
9listener.remove(); // Remember to remove the listener when it is no longer needed
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const myMessageDismissedHandler = (message) => {5 // Do something with the dismissed message6};7
8const listener = InAppMessaging.onMessageDismissed(myMessageDismissedHandler);9
10listener.remove(); // Remember to remove the listener when it is no longer needed
InAppMessaging.onMessageActionTaken
1import { onMessageActionTaken } from 'aws-amplify/in-app-messaging';2
3const myMessageActionTakenHandler = (message) => {4 // Do something with the message action was taken against5};6
7const listener = onMessageActionTaken(myMessageActionTakenHandler);8
9listener.remove(); // Remember to remove the listener when it is no longer needed
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const myMessageActionTakenHandler = (message) => {5 // Do something with the message action was taken against6};7
8const listener = InAppMessaging.onMessageActionTaken(9 myMessageActionTakenHandler10);11
12listener.remove(); // Remember to remove the listener when it is no longer needed
InAppMessaging.notifyMessageInteraction
The way to notify any interaction event listeners of your users' interactions with in-app messages in v6 has not changed in behavior. You will continue to use the notifyMessageInteraction
API to notify of interaction events. However, this API is now exported from the aws-amplify/in-app-messaging
path and the input parameters have been updated as follows:
- Instead of two position positional parameters (corresponding to
message
andinAppMessageInteractionEvent
), there are now two named parameters:message
andtype
(i.e. a single input object containing these properties). - Interaction event types have been changed from a SCREAMING_SNAKE_CASE convention to camelCase.
- The event type now expects a string instead of an
InAppMessageInteractionEvent
enumeration.
Input
V5
1message: InAppMessage;2
3/**4 * InAppMessageInteractionEvent.MESSAGE_RECEIVED_EVENT5 * InAppMessageInteractionEvent.MESSAGE_DISPLAYED_EVENT6 * InAppMessageInteractionEvent.MESSAGE_DISMISSED_EVENT7 * InAppMessageInteractionEvent.MESSAGE_ACTION_TAKEN_EVENT8 */9inAppMessageInteractionEvent: InAppMessageInteractionEvent;
V6
1input: {2 message: InAppMessage;3 type: 'messageReceived' | 'messageDisplayed' | 'messageDismissed' | 'messageActionTaken';4}
1import { notifyMessageInteraction } from 'aws-amplify/in-app-messaging';2
3const message = {4 // In-app message that you want to record an interaction on5}6
7notifyMessageInteraction({ message, type: 'messageDisplayed' });
1import { Notifications } from 'aws-amplify';2import { InAppMessageInteractionEvent } from '@aws-amplify/notifications'; 3const { InAppMessaging } = Notifications;4
5const message = {6 // In-app message that you want to record an interaction on7}8
9InAppMessaging.notifyMessageInteraction(10 message,11 InAppMessageInteractionEvent.MESSAGE_DISPLAYED_EVENT12);
InAppMessaging.setConflictHandler
The setConflictHandler
API in v6 has not changed in behavior; however, it is now exported from the aws-amplify/in-app-messaging
path.
1import { setConflictHandler } from 'aws-amplify/in-app-messaging';2
3const myConflictHandler = (messages) => {4 // Given an array of messages, return a single message5};6
7setConflictHandler(myConflictHandler);
1import { Notifications } from 'aws-amplify';2const { InAppMessaging } = Notifications;3
4const myConflictHandler = (messages) => {5 // Given an array of messages, return a single message6};7
8InAppMessaging.setConflictHandler(myConflictHandler);