Page updated Jan 23, 2024

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.

import { Amplify } from 'aws-amplify'; import amplifyconfig from './amplifyconfiguration.json'; import { initializeInAppMessaging } from 'aws-amplify/in-app-messaging'; Amplify.configure(amplifyconfig); initializeInAppMessaging();
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.

import { syncMessages } from 'aws-amplify/in-app-messaging'; await syncMessages();
1import { syncMessages } from 'aws-amplify/in-app-messaging';
2
3await syncMessages();
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; await InAppMessaging.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

import { record } from 'aws-amplify/analytics'; const event = { name: 'first_event', attributes: { color: 'red' }, metrics: { quantity: 10 } }; record(event);
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);
import { Analytics } from 'aws-amplify'; const event = { name: 'first_event', attributes: { color: 'red' }, metrics: { quantity: 10 } }; Analytics.record(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

import { dispatchEvent } from 'aws-amplify/in-app-messaging'; const event = { name: 'first_event', attributes: { color: 'red' }, metrics: { quantity: 10 } }; dispatchEvent(event);
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);
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const event = { name: 'first_event', attributes: { color: 'red' }, metrics: { quantity: 10 } }; InAppMessaging.dispatchEvent(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.

import { clearMessages } from 'aws-amplify/in-app-messaging'; await clearMessages();
1import { clearMessages } from 'aws-amplify/in-app-messaging';
2
3await clearMessages();
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; await InAppMessaging.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 and userInfo), there are now three named parameters: userId, userProfile and options (i.e. a single input object containing these properties).
  • The attributes property previously found under userInfo has been renamed to customProperties and can now be found under userProfile.
  • A new userAttributes property can be found under options.
  • New convenience properties name, email and plan can be found under userProfile. These properties are automatically merged into customProperties.
Input

V5

userId: string; userInfo: { attributes?: Record<string, string[]>; demographic?: { appVersion?: string; locale?: string; make?: string; model?: string; modelVersion?: string; platform?: string; platformVersion?: string; timezone?: string; }; location?: { city?: string; country?: string; latitude?: number; longitude?: number; postalCode?: string; region?: string; }; metrics?: Record<string, number>; }
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

input: { userId: string; userProfile: { customProperties?: Record<string, string[]>; demographic?: { appVersion?: string; locale?: string; make?: string; model?: string; modelVersion?: string; platform?: string; platformVersion?: string; timezone?: string; }; email?: string; location?: { city?: string; country?: string; latitude?: number; longitude?: number; postalCode?: string; region?: string; }; metrics?: Record<string, number>; name?: string; plan?: string; }; options?: { userAttributes?: Record<string, string[]>; }; }
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}
import { identifyUser } from 'aws-amplify/in-app-messaging'; const identifyUserInput = { userId: 'user-id', userProfile: { email: 'example@service.com', name: 'User A', plan: 'Standard' customProperties: { hobbies: ['cooking', 'knitting'], }, demographic: { appVersion: '1.0.0', locale: 'en_US', make: 'Apple', model: 'iPhone', modelVersion: '13', platform: 'iOS', platformVersion: '15', timezone: 'Americas/Los_Angeles' }, location: { city: 'Seattle', country: 'US', postalCode: '98121', region: 'WA', latitude: 0.0, longitude: 0.0 }, metrics: { logins: 157 }, }, }; await identifyUser(identifyUserInput);
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.0
29 },
30 metrics: {
31 logins: 157
32 },
33 },
34};
35
36await identifyUser(identifyUserInput);
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const userId = 'user-id'; const userInfo = { address: 'example@service.com', attributes: { hobbies: ['cooking', 'knitting'], }, demographic: { appVersion: '1.0.0', locale: 'en_US', make: 'Apple', model: 'iPhone', modelVersion: '13', platform: 'iOS', platformVersion: '15', timezone: 'Americas/Los_Angeles' }, location: { city: 'Seattle', country: 'US', postalCode: '98121', region: 'WA', latitude: 0.0, longitude: 0.0 }, metrics: { logins: 157 }, optOut: 'NONE' }; await InAppMessaging.identifyUser(userId, userInfo);
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.0
27 },
28 metrics: {
29 logins: 157
30 },
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

import { onMessageReceived } from 'aws-amplify/in-app-messaging'; const myMessageReceivedHandler = (message) => { // Do something with the received message }; const listener = onMessageReceived(myMessageReceivedHandler); listener.remove(); // Remember to remove the listener when it is no longer needed
1import { onMessageReceived } from 'aws-amplify/in-app-messaging';
2
3const myMessageReceivedHandler = (message) => {
4 // Do something with the received message
5};
6
7const listener = onMessageReceived(myMessageReceivedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const myMessageReceivedHandler = (message) => { // Do something with the received message }; const listener = InAppMessaging.onMessageReceived(myMessageReceivedHandler); listener.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 message
6};
7
8const listener = InAppMessaging.onMessageReceived(myMessageReceivedHandler);
9
10listener.remove(); // Remember to remove the listener when it is no longer needed

InAppMessaging.onMessageDisplayed

import { onMessageDisplayed } from 'aws-amplify/in-app-messaging'; const myMessageDisplayedHandler = (message) => { // Do something with the displayed message }; const listener = onMessageDisplayed(myMessageDisplayedHandler); listener.remove(); // Remember to remove the listener when it is no longer needed
1import { onMessageDisplayed } from 'aws-amplify/in-app-messaging';
2
3const myMessageDisplayedHandler = (message) => {
4 // Do something with the displayed message
5};
6
7const listener = onMessageDisplayed(myMessageDisplayedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const myMessageDisplayedHandler = (message) => { // Do something with the displayed message }; const listener = InAppMessaging.onMessageDisplayed(myMessageDisplayedHandler); listener.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 message
6};
7
8const listener = InAppMessaging.onMessageDisplayed(myMessageDisplayedHandler);
9
10listener.remove(); // Remember to remove the listener when it is no longer needed

InAppMessaging.onMessageDismissed

import { onMessageDismissed } from 'aws-amplify/in-app-messaging'; const myMessageDismissedHandler = (message) => { // Do something with the dismissed message }; const listener = onMessageDismissed(myMessageDismissedHandler); listener.remove(); // Remember to remove the listener when it is no longer needed
1import { onMessageDismissed } from 'aws-amplify/in-app-messaging';
2
3const myMessageDismissedHandler = (message) => {
4 // Do something with the dismissed message
5};
6
7const listener = onMessageDismissed(myMessageDismissedHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const myMessageDismissedHandler = (message) => { // Do something with the dismissed message }; const listener = InAppMessaging.onMessageDismissed(myMessageDismissedHandler); listener.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 message
6};
7
8const listener = InAppMessaging.onMessageDismissed(myMessageDismissedHandler);
9
10listener.remove(); // Remember to remove the listener when it is no longer needed

InAppMessaging.onMessageActionTaken

import { onMessageActionTaken } from 'aws-amplify/in-app-messaging'; const myMessageActionTakenHandler = (message) => { // Do something with the message action was taken against }; const listener = onMessageActionTaken(myMessageActionTakenHandler); listener.remove(); // Remember to remove the listener when it is no longer needed
1import { onMessageActionTaken } from 'aws-amplify/in-app-messaging';
2
3const myMessageActionTakenHandler = (message) => {
4 // Do something with the message action was taken against
5};
6
7const listener = onMessageActionTaken(myMessageActionTakenHandler);
8
9listener.remove(); // Remember to remove the listener when it is no longer needed
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const myMessageActionTakenHandler = (message) => { // Do something with the message action was taken against }; const listener = InAppMessaging.onMessageActionTaken( myMessageActionTakenHandler ); listener.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 against
6};
7
8const listener = InAppMessaging.onMessageActionTaken(
9 myMessageActionTakenHandler
10);
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 and inAppMessageInteractionEvent), there are now two named parameters: message and type (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

message: InAppMessage; /** * InAppMessageInteractionEvent.MESSAGE_RECEIVED_EVENT * InAppMessageInteractionEvent.MESSAGE_DISPLAYED_EVENT * InAppMessageInteractionEvent.MESSAGE_DISMISSED_EVENT * InAppMessageInteractionEvent.MESSAGE_ACTION_TAKEN_EVENT */ inAppMessageInteractionEvent: InAppMessageInteractionEvent;
1message: InAppMessage;
2
3/**
4 * InAppMessageInteractionEvent.MESSAGE_RECEIVED_EVENT
5 * InAppMessageInteractionEvent.MESSAGE_DISPLAYED_EVENT
6 * InAppMessageInteractionEvent.MESSAGE_DISMISSED_EVENT
7 * InAppMessageInteractionEvent.MESSAGE_ACTION_TAKEN_EVENT
8 */
9inAppMessageInteractionEvent: InAppMessageInteractionEvent;

V6

input: { message: InAppMessage; type: 'messageReceived' | 'messageDisplayed' | 'messageDismissed' | 'messageActionTaken'; }
1input: {
2 message: InAppMessage;
3 type: 'messageReceived' | 'messageDisplayed' | 'messageDismissed' | 'messageActionTaken';
4}
import { notifyMessageInteraction } from 'aws-amplify/in-app-messaging'; const message = { // In-app message that you want to record an interaction on } notifyMessageInteraction({ message, type: 'messageDisplayed' });
1import { notifyMessageInteraction } from 'aws-amplify/in-app-messaging';
2
3const message = {
4 // In-app message that you want to record an interaction on
5}
6
7notifyMessageInteraction({ message, type: 'messageDisplayed' });
import { Notifications } from 'aws-amplify'; import { InAppMessageInteractionEvent } from '@aws-amplify/notifications'; const { InAppMessaging } = Notifications; const message = { // In-app message that you want to record an interaction on } InAppMessaging.notifyMessageInteraction( message, InAppMessageInteractionEvent.MESSAGE_DISPLAYED_EVENT );
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 on
7}
8
9InAppMessaging.notifyMessageInteraction(
10 message,
11 InAppMessageInteractionEvent.MESSAGE_DISPLAYED_EVENT
12);

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.

import { setConflictHandler } from 'aws-amplify/in-app-messaging'; const myConflictHandler = (messages) => { // Given an array of messages, return a single message }; setConflictHandler(myConflictHandler);
1import { setConflictHandler } from 'aws-amplify/in-app-messaging';
2
3const myConflictHandler = (messages) => {
4 // Given an array of messages, return a single message
5};
6
7setConflictHandler(myConflictHandler);
import { Notifications } from 'aws-amplify'; const { InAppMessaging } = Notifications; const myConflictHandler = (messages) => { // Given an array of messages, return a single message }; InAppMessaging.setConflictHandler(myConflictHandler);
1import { Notifications } from 'aws-amplify';
2const { InAppMessaging } = Notifications;
3
4const myConflictHandler = (messages) => {
5 // Given an array of messages, return a single message
6};
7
8InAppMessaging.setConflictHandler(myConflictHandler);