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 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

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}

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.0
29    },
30    metrics: {
31      logins: 157
32    },
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.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

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

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

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

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

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

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

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

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

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;

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 on
5}
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 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.

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);

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);

Resolve conflicts