-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: update migration guides for Analytics, InApp Messaging and Pus…
…h Notifications (#6583) * feat: update migration guides for Analytics and InApp Messaging * feat: update guide for push notifications * chore: move the guides to its respective sections * Update src/pages/[platform]/build-a-backend/more-features/in-app-messaging/in-app-messaging-migration-guide/index.mdx Co-authored-by: Jim Blanchard <[email protected]> * chore: update platforms list * update description on the meta tag --------- Co-authored-by: Rene Brandel <[email protected]> Co-authored-by: Jim Blanchard <[email protected]>
- Loading branch information
3 people
authored
Dec 5, 2023
1 parent
35a6152
commit a7ecf1d
Showing
6 changed files
with
473 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
137 changes: 137 additions & 0 deletions
137
...rm]/build-a-backend/more-features/analytics/analytics-migration-guide/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,137 @@ | ||
| import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; | ||
|
|
||
| export const meta = { | ||
| title: 'Migrate from v5 to v6', | ||
| description: 'Learn more about the migration steps to upgrade Analytics APIs for Amplify JavaScript v5 to v6', | ||
| platforms: [ | ||
| 'javascript', | ||
| 'react-native', | ||
| 'angular', | ||
| 'nextjs', | ||
| 'react', | ||
| 'vue' | ||
| ] | ||
| }; | ||
|
|
||
| export const getStaticPaths = async () => { | ||
| return getCustomStaticPath(meta.platforms); | ||
| }; | ||
|
|
||
| export function getStaticProps(context) { | ||
| return { | ||
| props: { | ||
| platform: context.params.platform, | ||
| meta | ||
| } | ||
| }; | ||
| } | ||
|
|
||
| ## Record and Configuration APIs | ||
|
|
||
| As of v6 of Amplify JavaScript, you will now import the functional API’s directly from the `aws-amplify/analytics` path as shown below. | ||
|
|
||
| Note: Red lines of code are v5 and Green lines are v6. | ||
|
|
||
| ```diff | ||
| - import { Analytics } from 'aws-amplify'; | ||
| + import { enable, disable, record, configureAutoTrack } from 'aws-amplify/analytics'; | ||
|
|
||
| - Analytics.disable(); | ||
| + disable(); | ||
|
|
||
| - Analytics.enable(); | ||
| + enable(); | ||
|
|
||
| - Analytics.record({ | ||
| - name: 'albumVisit', | ||
| - attributes: {}, | ||
| - metrics: { minutesListened: 30 } | ||
| - }); | ||
|
|
||
| + record({ | ||
| + event: { | ||
| + name: 'albumVisit', | ||
| + attributes: { genre: '', artist: '' } | ||
| + } | ||
| + }); | ||
|
|
||
| - Analytics.autoTrack('session', { | ||
| - // REQUIRED, turn on/off the auto tracking | ||
| - enable: true, | ||
| - // OPTIONAL, the attributes of the event, you can either pass an object or a function | ||
| - // which allows you to define dynamic attributes | ||
| - attributes: { | ||
| - attr: 'attr' | ||
| - }, | ||
| - // OPTIONAL, the service provider, by default is the Amazon Pinpoint | ||
| - provider: 'AWSPinpoint' | ||
| - }); | ||
|
|
||
| + configureAutoTrack({ | ||
| + // REQUIRED, turn on/off the auto tracking | ||
| + enable: true, | ||
| + // REQUIRED, the event type, it's one of 'event', 'pageView' or 'session' | ||
| + type: 'session', | ||
| + // OPTIONAL, additional options for the tracked event. | ||
| + options: { | ||
| + // OPTIONAL, the attributes of the event | ||
| + attributes: { | ||
| + customizableField: 'attr' | ||
| + } | ||
| + } | ||
| + }); | ||
| ``` | ||
| ## Analytics.identifyUser | ||
|
|
||
| You can identify an Analytics user with the `identifyUser` API, | ||
|
|
||
| ```ts | ||
| import { identifyUser } from 'aws-amplify/analytics'; | ||
|
|
||
| identifyUser({ | ||
| userId: "<user-id>", // If the user was signed in through Amplify Auth's signIn method you can retrieve the current user's ID from there. | ||
| userProfile | ||
| }); | ||
|
|
||
| ``` | ||
| ## Streaming data | ||
| You can stream analytics data to Kinesis. To configure Kinesis with Amplify, reference the [Installation and Configuration](https://docs.amplify.aws/react/build-a-backend/more-features/analytics/streaming-data/#installation-and-configuration) section of the documentation. Below is an example on how to stream data and flush events, | ||
|
|
||
| ```ts | ||
| import { record, flushEvents } from 'aws-amplify/analytics/kinesis'; | ||
|
|
||
| record({ | ||
| data: { | ||
| // The data blob to put into the record | ||
| }, | ||
| partitionKey: 'myPartitionKey', | ||
| streamName: 'myKinesisStream' | ||
| }); | ||
|
|
||
| flushEvents(); | ||
| ``` | ||
| Finally, let's look at the difference in how to personalize recommendations, | ||
|
|
||
| ```diff | ||
| - import { Analytics, AmazonPersonalizeProvider } from 'aws-amplify'; | ||
| - Analytics.addPluggable(new AmazonPersonalizeProvider()); | ||
|
|
||
| + import { record } from 'aws-amplify/analytics/personalize'; | ||
|
|
||
|
|
||
| - Analytics.record({ | ||
| - eventType: "Identify", | ||
| - properties: { | ||
| - "userId": "<USER_ID>" | ||
| - } | ||
| - }, 'AmazonPersonalize'); | ||
|
|
||
| + record({ | ||
| + eventType: "Identify", | ||
| + properties: { | ||
| + userId: "<USER_ID>" | ||
| + } | ||
| + }); | ||
|
|
||
| ``` | ||
| Notice that in v5, the `Analytics.record` API takes in a second parameter with the string value `AmazonPersonalize` whereas in v6, the `record` function is imported from the `aws-amplify/analytics/personalize` subpath and takes only one parameter. |
156 changes: 156 additions & 0 deletions
156
...ckend/more-features/in-app-messaging/in-app-messaging-migration-guide/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,156 @@ | ||
| import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; | ||
|
|
||
| export const meta = { | ||
| title: 'Migrate from v5 to v6', | ||
| description: 'Learn more about the migration steps to upgrade In-app messaging APIs for Amplify JavaScript v5 to v6', | ||
| platforms: ['javascript', 'react-native', 'angular', 'nextjs', 'react', 'vue'] | ||
| }; | ||
|
|
||
| export const getStaticPaths = async () => { | ||
| return getCustomStaticPath(meta.platforms); | ||
| }; | ||
|
|
||
| export function getStaticProps(context) { | ||
| return { | ||
| props: { | ||
| platform: context.params.platform, | ||
| meta | ||
| } | ||
| }; | ||
| } | ||
|
|
||
| ## Initialization and syncing messages | ||
|
|
||
| As of v6 of Amplify JavaScript, you will now import the functional API’s directly from the `aws-amplify/in-app-messaging` path as shown below. | ||
|
|
||
| Note: Red lines of code are v5 and Green lines are v6. | ||
|
|
||
| ```diff | ||
| - import { Notifications } from 'aws-amplify'; | ||
|
|
||
| + import { | ||
| + initializeInAppMessaging, | ||
| + syncMessages, | ||
| + setConflictHandler | ||
| + } from 'aws-amplify/in-app-messaging'; | ||
|
|
||
| - const { InAppMessaging } = Notifications; | ||
| + initializeInAppMessaging(); | ||
|
|
||
| - InAppMessaging.syncMessages(); | ||
| + syncMessages(); | ||
| - InAppMessaging.setConflictHandler(myConflictHandler); | ||
| + setConflictHandler(myConflictHandler); | ||
|
|
||
| ``` | ||
|
|
||
| ## Dispatch event and clear messages | ||
|
|
||
| ```diff | ||
| - import { Notifications } from 'aws-amplify'; | ||
|
|
||
| + import { | ||
| + dispatchEvent, | ||
| + initializeInAppMessaging, | ||
| + clearMessages, | ||
| + } from 'aws-amplify/in-app-messaging'; | ||
|
|
||
| - const { InAppMessaging } = Notifications; | ||
| + initializeInAppMessaging(); | ||
|
|
||
| const sendEvent = (eventName: string) => { | ||
| - InAppMessaging.dispatchEvent({ name: eventName }); | ||
| + dispatchEvent({ name: eventName }); | ||
| } | ||
|
|
||
| - await InAppMessaging.clearMessages(); | ||
| + await clearMessages(); | ||
|
|
||
| ``` | ||
|
|
||
| ## IdentifyUser | ||
|
|
||
| The input format of the `identifyUser` has changed slightly. The below table shows the differences in the input type. | ||
|
|
||
| | Difference | v5 | v6 | | ||
| | ---- | ---- | ----------- | | ||
| | API input | Two separate parameters -- `userId`, `userInfo` | Single object containing `userId`, `userProfile`, `options` | | ||
| | `attributes` property | `attributes` under `userInfo` | changed to `customProperties` under `userProfile` | | ||
| | `userAttributes` property | NA | `userAttributes` under `options` | | ||
| | convenience properties | NA | `name`, `email`, `plan` under `userProfile` | | ||
|
|
||
| ```diff | ||
| import { identifyUser } from 'aws-amplify/in-app-messaging'; | ||
|
|
||
| - const userInfo = { | ||
| - address: '' // E.g. A device token or email address | ||
| - optOut: '' // Either ALL or NONE | ||
| - }; | ||
|
|
||
| + const identifyUserInput = { | ||
| + userId: '', // E.g. user-id | ||
| + userProfile: { | ||
| + email: '', // E.g. [email protected] | ||
| + name: '', // E.g. name-of-the-user | ||
| + plan: '' // E.g. plan-they-subscribe-to | ||
| + customProperties: { | ||
| + // E.g. hobbies: ['cooking', 'knitting'], | ||
| + }, | ||
| + }, | ||
| + options: { | ||
| + address: '' // E.g. A device token or email address | ||
| + optOut: '' // Either ALL or NONE | ||
| + userAttributes: { | ||
| + // E.g. interests: ['soccer', 'shoes'], | ||
| + } | ||
| + }, | ||
| + }; | ||
|
|
||
| - await InAppMessaging.identifyUser('some-user-id', userInfo); | ||
| + await identifyUser(identifyUserInput); | ||
|
|
||
| ``` | ||
|
|
||
| # Handling Interaction events | ||
|
|
||
| ```diff | ||
| - import { Notifications } from 'aws-amplify'; | ||
|
|
||
| + import { | ||
| + initializeInAppMessaging, | ||
| + onMessageReceived, | ||
| + onMessageDisplayed, | ||
| + onMessageDismissed, | ||
| + onMessageActionTaken, | ||
| + } from 'aws-amplify/in-app-messaging'; | ||
|
|
||
| - const { InAppMessaging } = Notifications; | ||
| - InAppMessaging.syncMessages(); | ||
|
|
||
| + initializeInAppMessaging(); | ||
|
|
||
| const myMessageReceivedHandler = (message) => { | ||
| // Do something with the received message | ||
| }; | ||
| const myMessageDisplayedHandler = (message) => { | ||
| // Do something with the displayed message | ||
| }; | ||
| const myMessageDismissedHandler = (message) => { | ||
| // Do something with the dismissed message | ||
| }; | ||
| const myMessageActionTakenHandler = (message) => { | ||
| // Do something with the message action was taken against | ||
| }; | ||
|
|
||
| - InAppMessaging.onMessageReceived(myMessageReceivedHandler); | ||
| + onMessageReceived(myMessageReceivedHandler); | ||
|
|
||
| - InAppMessaging.onMessageDisplayed(myMessageDisplayedHandler); | ||
| + onMessageDisplayed(myMessageDisplayedHandler); | ||
|
|
||
| - InAppMessaging.onMessageDismissed(myMessageDismissedHandler); | ||
| + onMessageDismissed(myMessageDismissedHandler); | ||
|
|
||
| - InAppMessaging.onMessageActionTaken(myMessageActionTakenHandler); | ||
| + onMessageActionTaken(myMessageActionTakenHandler); | ||
| ``` |
Oops, something went wrong.