Name:
interface
Value:
Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Page updated Apr 29, 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();

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

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[]>; };
}
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);
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);

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

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

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

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

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;

V6

input: {
message: InAppMessage;
type: 'messageReceived' | 'messageDisplayed' | 'messageDismissed' | 'messageActionTaken';
}
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' });
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
);

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);
import { Notifications } from 'aws-amplify';
const { InAppMessaging } = Notifications;
const myConflictHandler = (messages) => {
// Given an array of messages, return a single message
};
InAppMessaging.setConflictHandler(myConflictHandler);