In-App Messaging

Amplify UI In-App Messaging provides UI components for displaying in-app messages.

Overview

In-App Messaging allows you to better engage users with contextually appropriate messages rendered on events triggered by their activity while using your application. Create messages that look native to your application and deliver them to your users all without additional code changes.

@aws-amplify/ui-react v5

The @aws-amplify/ui-react package is currently on version 6. Working with@aws-amplify/ui-react version 5 or earlier? See our migration guide.

Amplify UI In-App Messaging uses the Amplify In-App Messaging API and Amazon Pinpoint.

Prerequisites

Create an In-App Messaging campaign

Install the required dependencies

Getting Started

Next.js 13.4+ introduces App Router with the usage of Server Components. Amplify UI components are interactive and designed to work on the client side. To use them inside of Server Components you must wrap them in a Client Component with "use client". For more info, visit Next.js third party package documentation.

If you are using Next.js Pages Router, no changes are required to use Amplify UI components.

Integration with your application can be done with the InAppMessagingProvider and InAppMessageDisplay components directly, or wrap your app in withInAppMessaging (a React Higher-Order Component):

import React, { useEffect } from 'react';
import { Amplify } from 'aws-amplify';
import {
  initializeInAppMessaging,
  syncMessages,
} from 'aws-amplify/in-app-messaging';
import { Text } from '@aws-amplify/ui-react';
import {
  InAppMessagingProvider,
  InAppMessageDisplay,
} from '@aws-amplify/ui-react-notifications';

import '@aws-amplify/ui-react/styles.css';

import config from './aws-exports';

Amplify.configure(config);
initializeInAppMessaging();

function App() {
  useEffect(() => {
    // sync remote in-app messages
    syncMessages();
  }, []);

  return (
    <InAppMessagingProvider>
      <InAppMessageDisplay />
      <Text>In-App Messaging Example</Text>
    </InAppMessagingProvider>
  );
}

export default App;

import React, { useEffect } from 'react';
import { Amplify } from 'aws-amplify';
import {
  initializeInAppMessaging,
  syncMessages,
} from 'aws-amplify/in-app-messaging';
import { Text } from '@aws-amplify/ui-react';
import { withInAppMessaging } from '@aws-amplify/ui-react-notifications';
import '@aws-amplify/ui-react/styles.css';

import config from './aws-exports';

Amplify.configure(config);
initializeInAppMessaging();

function App() {
  useEffect(() => {
    // sync remote in-app messages
    syncMessages();
  }, []);

  return <Text>In-App Messaging Example</Text>;
}

export default withInAppMessaging(App);

InAppMessaging.syncMessages is an asynchronous function that handles syncing remote in-app messages with the end user application.

`InAppMessagingProvider` and `useInAppMessaging`

InAppMessagingProvider exposes the value of the InAppMessagingContext (a React context) to its children. useInAppMessaging can be used to directly interact with InAppMessagingContext from within InAppMessagingProvider.

useInAppMessaging exposes the following functions and values of the InAppMessagingContext:

Name	Description	Type
clearMessage	Removes the current in-app message (if any) from context state	`() => void`
displayMessage	Render a local in-app message	`(message: Message) => void`
message	current in-app message (if any) loaded in context state	`Message \| null`

In some use cases, you may want to forgo the usage of the default UI handling altogether while still leveraging the Amplify provided In-App Messaging React context and provider for in-app message context state. This can be achieved by wrapping your application in an InAppMessagingProvider and utilizing the useInAppMessaging hook to expose the values of the InAppMessagingContext.

import {
  InAppMessagingProvider,
  useInAppMessaging
} from '@aws-amplify/ui-react-notifications';
import '@aws-amplify/ui-react/styles.css';

import { Home } from './src/Home';

const MyInAppMessageDisplay = () => {
  const { inAppMessage } = useInAppMessaging();

  // ...do something with inAppMessage
};

const App = () => {
  return (
    <InAppMessagingProvider>
      <MyInAppMessageDisplay />
      <Home />
    </InAppMessagingProvider>
  );
};

`InAppMessageDisplay`

InAppMessageDisplay handles the display and lifecycle of an in-app message.

Name	Description	Type
components?	Message override UI components	`MessageComponents`

The `MessageComponents` prop

Functional UI components that render in-app message content

Name	Description	Type
BannerMessage?	Banner UI component (top, middle, and bottom layouts)	`BannerMessageProps`
CarouselMessage?	Carousel UI component (default provided for React Native only)	`CarouselMessageProps`
FullScreenMessage?	FullScreen UI component	`FullScreenMessageProps`
ModalMessage?	Modal UI component	`ModalMessageProps`

Integrate Custom Components

You may provide your own In-App Messaging UI components to override the default Amplify provided UI components by utilizing the components prop of InAppMessagingProvider.

import React, { useCallback, useEffect } from 'react';
import { Amplify } from 'aws-amplify';
import {
  initializeInAppMessaging,
  syncMessages,
} from 'aws-amplify/in-app-messaging';
import { Button, Flex, Text } from '@aws-amplify/ui-react';
import {
  useInAppMessaging,
  withInAppMessaging,
} from '@aws-amplify/ui-react-notifications';

import '@aws-amplify/ui-react/styles.css';

import config from './aws-exports';

Amplify.configure(config);
initializeInAppMessaging();

const CustomBannerMessage = (props) => {
  return (
    <Flex
      alignItems="center"
      borderRadius="xs"
      position="absolute"
      padding="xl"
      backgroundColor="teal.20"
      right="xl"
      testId="custom-banner"
    >
      <Text fontWeight="bold">{props.header.content}</Text>
      <Button onClick={props.onClose}>Close!</Button>
    </Flex>
  );
};

function App() {
  const { displayMessage } = useInAppMessaging();

  useEffect(() => {
    // sync remote in-app messages
    syncMessages();
  }, []);

  const displayCustomBannerMessage = useCallback(
    () =>
      displayMessage({
        content: [{ header: { content: 'Hello World!' } }],
        id: 'Custom message',
        layout: 'TOP_BANNER',
      }),
    [displayMessage]
  );

  // display custom message component on initial render
  useEffect(displayCustomBannerMessage, [displayCustomBannerMessage]);

  return (
    <Button margin="medium" onClick={displayCustomBannerMessage}>
      Display Custom Banner Message
    </Button>
  );
}

export default withInAppMessaging(App, {
  components: { BannerMessage: CustomBannerMessage },
});

Style Override

The default Amplify UI components handle custom style using the styles prop:

import React, { useCallback, useEffect } from 'react';
import { Amplify } from 'aws-amplify';
import {
  initializeInAppMessaging,
  syncMessages,
} from 'aws-amplify/in-app-messaging';
import { Button } from '@aws-amplify/ui-react';
import {
  InAppMessageDisplay,
  useInAppMessaging,
  withInAppMessaging,
} from '@aws-amplify/ui-react-notifications';
import '@aws-amplify/ui-react/styles.css';

import config from './aws-exports';

Amplify.configure(config);
initializeInAppMessaging();

const StyledModalMessage = (props) => (
  <InAppMessageDisplay.ModalMessage
    {...props}
    style={{ container: { backgroundColor: 'antiquewhite' } }}
  />
);

function App() {
  const { displayMessage } = useInAppMessaging();

  useEffect(() => {
    // sync remote in-app messages
    syncMessages();
  }, []);

  const displayStyledModalMessage = useCallback(
    () =>
      displayMessage({
        content: [{ header: { content: 'Hello World!' } }],
        id: 'styled message',
        layout: 'MODAL',
      }),
    [displayMessage]
  );

  // display message component on initial render
  useEffect(displayStyledModalMessage, [displayStyledModalMessage]);

  return (
    <Button margin="medium" onClick={displayStyledModalMessage}>
      Display Custom Modal Message
    </Button>
  );
}

export default withInAppMessaging(App, {
  components: { ModalMessage: StyledModalMessage },
});

Available style props:

The default In-App Messaging components do not handle dark mode using the ThemeProvider at this time

Name	Description	Type
body?	style applied to the message body	`React.CSSProperties`
closeIconButton?	style applied to the close button	`React.CSSProperties`
container?	style applied to the primary container of the message component	`React.CSSProperties`
header?	style applied to the message header	`React.CSSProperties`
image?	style applied to the message image	`React.CSSProperties`
primaryButton?	style applied to the message primary button	`React.CSSProperties`
secondaryButton?	style applied to the message secondary button	`React.CSSProperties`