Add More Display Options to getMessages (#123)

* adds more display options to getMessages

* adds tests and example app integration with new display setting

* adds documentation

* updates readme

* updates readme

* updates readme

Author: martinmckenna

.gitignore

@@ -10,3 +10,4 @@ log
 *.log
 results
 browserstack.json
+.DS_Store

README.md

@@ -48,7 +48,7 @@ Below are the methods this SDK exposes. See [Iterable's API Docs](https://api.it
 
 | Method Name           	| Description                                                                                                               	|
 |-----------------------	|---------------------------------------------------------------------------------------------------------------------------	|
-| [`getInAppMessages`](#getInAppMessages)    	| Either return in-app messages as a Promise or automatically paint them to the DOM if the second argument is passed `true` 	|
+| [`getInAppMessages`](#getInAppMessages)    	| Either return in-app messages as a Promise or automatically paint them to the DOM if the second argument is passed `DisplayOptions` 	|
 | [`initialize`](#initialize)        	| Method for identifying users and setting a JWT                                                                            	|
 | [`track`](#track)               	| Track custom events                                                                                                       	|
 | [`trackInAppClick`](#trackInAppClick)     	| Track when a user clicks on a button or link within a message                                                             	|
@@ -60,7 +60,7 @@ Below are the methods this SDK exposes. See [Iterable's API Docs](https://api.it
 | [`updateCart`](#updateCart)          	| Update _shoppingCartItems_ field on user profile                                                                          	|
 | [`updateSubscriptions`](#updateSubscriptions) 	| Updates user's subscriptions                                                                                              	|
 | [`updateUser`](#updateUser)          	| Change data on a user's profile or create a user if none exists                                                           	|
-| [`updateUserEmail`](#updateUserEmail)     	| Change a user's email address                                                                                             	|
+| [`updateUserEmail`](#updateUserEmail)     	| Change a user's email and reauthenticate user with the new email address (in other words, we will call `setEmail` for you)                                                                                             	|
 
 # Usage
 
@@ -69,7 +69,7 @@ Below are the methods this SDK exposes. See [Iterable's API Docs](https://api.it
 API [(see required API payload here)](https://api.iterable.com/api/docs#In-app_getMessages):
 
 ```ts
-getInAppMessages: (payload: InAppMessagesRequestParams, showMessagesAutomatically?: boolean) => Promise<TrackConsumeData> | PaintInAppMessageData
+getInAppMessages: (payload: InAppMessagesRequestParams, showMessagesAutomatically?: boolean | { display: 'deferred' | 'immediate' }) => Promise<TrackConsumeData> | PaintInAppMessageData
 ```
 
 SDK Specific Options:
@@ -112,7 +112,7 @@ getInAppMessages({
   .catch()
 ```
 
-or
+or if you want to show messages automatically
 
 ```ts
 import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
@@ -135,14 +135,65 @@ const {
       topOffset: '20px'
     }
   },
-  true
+  { display: 'immediate' }
 );
 
 request()
   .then()
   .catch();
 ```
 
+or if you want to show messages with your own custom filtering/sorting and choose to display later:
+
+```ts
+import { 
+  getInAppMessages,
+  sortInAppMessages,
+  filterHiddenInAppMessages
+} from '@iterable/web-sdk/dist/inapp';
+
+const { 
+  request,
+  pauseMessageStream, 
+  resumeMessageStream,
+  triggerDisplayMessages
+} = getInAppMessages(
+  { 
+    count: 20,
+    packageName: 'my-website',
+    displayInterval: 5000,
+    onOpenScreenReaderMessage:
+      'hey screen reader here telling you something just popped up on your screen!',
+    onOpenNodeToTakeFocus: 'input',
+    closeButton: {
+      color: 'red',
+      size: '16px',
+      topOffset: '20px'
+    }
+  },
+  { display: 'deferred' }
+);
+
+request()
+  .then(response => {
+    /* do your own manipulation here */
+    const filteredMessages = doStuffToMessages(response.data.inAppMessages);
+
+    /* also feel free to take advantage of the sorting/filtering methods we use internally */
+    const furtherManipulatedMessages = sortInAppMessages(
+      filterHiddenInAppMessages(response.data.inAppMessages)
+    ) as InAppMessage[];
+
+    /* then display them whenever you want */
+    triggerDisplayMessages(furtherManipulatedMessages)
+  })
+  .catch();
+```
+
+:rotating_light: *PLEASE NOTE*: If you choose the `deferred` option, we will _not_ do any filtering or sorting on the messages internally. You will get the messages exactly as they come down from the API, untouched. This means you may (for example) show in-app messages marked `read` or show the messages in the wrong order based on `priority`.
+
+If you want to keep the default sorting and filtering, please take advantage of the `sortInAppMessages` and `filterHiddenInAppMessages` methods we provide.
+
 ## initialize
 
 API:
@@ -171,6 +222,24 @@ const { clearRefresh, setEmail, setUserID, logout } = initialize(
 )
 ```
 
+:rotating_light: *PLEASE NOTE*: When you call `updateUserEmail`, we will invoke `yourAsyncJWTGenerationMethod` with the new email address even if you originally authenticated with a user ID, so if you chose to first call `setUserID`, you will need to ensure your backend can also handle JWT generation with email addresses. In other words, you need to make sure both invocations of your async JWT generation method work:
+
+```ts
+/* 
+  the key "email" can be whatever. You just need to make sure your method can be passed an
+  email somehow when originally calling "initialize"
+*/
+yourAsyncJWTGenerationMethod({ email: '[email protected]' })
+```
+
+```ts
+/* 
+  the key "userID" can be whatever. You just need to make sure your method can be passed a
+  user ID somehow when originally calling "initialize"
+*/
+yourAsyncJWTGenerationMethod({ userID: '1sfds32' })
+```
+
 ## track
 
 API [(see required API payload here)](https://api.iterable.com/api/docs#events_track):
@@ -529,7 +598,7 @@ import { baseAxiosRequest } from '@iterable/web-sdk/dist/request';
 
 ## I want to automatically show my in-app messages with a delay between each
 
-This SDK allows that. Simply call the `getMessages` method but pass `true` as the second parameter. This will expose some methods used to make the request to show the messages and pause and resume the queue.
+This SDK allows that. Simply call the `getMessages` method but pass `{ display: 'immediate' }` as the second parameter. This will expose some methods used to make the request to show the messages and pause and resume the queue.
 
 Normally to request a list of in-app messages, you'd make a request like this:
 
@@ -579,7 +648,7 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
               count: 20,
               packageName: 'my-website'
             },
-            true
+            { display: 'immediate' }
           );
 
           /* trigger the start of message presentation */
@@ -621,7 +690,7 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
               animationDuration: 400,
               handleLinks: 'external-new-tab'
             },
-            true
+            { display: 'immediate' }
           );
 
           /* trigger the start of message presentation */
@@ -658,7 +727,7 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
               count: 20,
               packageName: 'my-website'
             },
-            true
+            { display: 'immediate' }
           );
 
           /* trigger the start of message presentation */
@@ -679,6 +748,61 @@ import { getInAppMessages } from '@iterable/web-sdk/dist/inapp';
 })();
 ```
 
+Finally, you can also choose to do your own manipulation to the messages before choosing to display them:
+
+```ts
+import { initialize } from '@iterable/web-sdk/dist/authorization';
+import { 
+  getInAppMessages,
+  sortInAppMessages,
+  filterHiddenInAppMessages
+} from '@iterable/web-sdk/dist/inapp';
+
+(() => {
+  const { setUserID } = initialize(
+    'YOUR_API_KEY_HERE',
+    ({ email, userID }) => yourAsyncJWTGeneratorMethod(({ email, userID })).then(({ jwt_token }) => jwt_token)
+  );
+
+  yourAsyncLoginMethod()
+    .then(response => {
+      setUserID(response.user_id)
+        .then(() => {
+          const { 
+            request,
+            pauseMessageStream, 
+            resumeMessageStream
+           } = getInAppMessages(
+            { 
+              count: 20,
+              packageName: 'my-website'
+            },
+            { display: 'deferred' }
+          );
+
+          /* trigger the start of message presentation */
+          request()
+            .then(response => {
+              /* do your own manipulation here */
+              const filteredMessages = doStuffToMessages(response.data.inAppMessages);
+
+              /* 
+                also feel free to take advantage of the sorting/filtering 
+                methods we use internally 
+              */
+              const furtherManipulatedMessages = sortInAppMessages(
+                filterHiddenInAppMessages(response.data.inAppMessages)
+              ) as InAppMessage[];
+
+              /* then display them whenever you want */
+              triggerDisplayMessages(furtherManipulatedMessages)
+            })
+            .catch();
+        })
+    })
+})();
+```
+
 ## I want my messages to look good on every device and be responsive
 
 This SDK already handles that for you. The rules for the in-app message presentation varies based on which display type you've selected. Here's a table to explain how it works:

example/src/index.ts

@@ -31,7 +31,12 @@ import {
     }
   );
 
-  const { request, pauseMessageStream, resumeMessageStream } = getInAppMessages(
+  const {
+    request,
+    pauseMessageStream,
+    resumeMessageStream,
+    triggerDisplayMessages
+  } = getInAppMessages(
     {
       count: 20,
       displayInterval: 1000,
@@ -52,7 +57,7 @@ import {
         // topOffset: '6%'
       }
     },
-    true
+    { display: 'deferred' }
   );
 
   const startBtn = document.getElementById('start');
@@ -68,6 +73,7 @@ import {
       startBtn.className = 'disabled';
       request()
         .then((response) => {
+          triggerDisplayMessages(response.data.inAppMessages);
           startBtn.innerText = `${response.data.inAppMessages.length} total messages retrieved!`;
         })
         .catch(console.warn);

src/inapp/inapp.ts

@@ -59,7 +59,20 @@ export function getInAppMessages(
 };
 export function getInAppMessages(
   payload: InAppMessagesRequestParams,
-  showInAppMessagesAutomatically?: boolean
+  showInAppMessagesAutomatically: { display: 'immediate' | 'deferred' }
+): {
+  pauseMessageStream: () => void;
+  resumeMessageStream: () => Promise<HTMLIFrameElement | ''>;
+  request: () => IterablePromise<InAppMessageResponse>;
+  triggerDisplayMessages: (
+    messages: Partial<InAppMessage>[]
+  ) => Promise<HTMLIFrameElement | ''>;
+};
+export function getInAppMessages(
+  payload: InAppMessagesRequestParams,
+  showInAppMessagesAutomatically?:
+    | boolean
+    | { display: 'immediate' | 'deferred' }
 ) {
   clearMessages();
 
@@ -499,6 +512,18 @@ export function getInAppMessages(
       return Promise.resolve('');
     };
 
+    const maybeDisplayFn =
+      typeof showInAppMessagesAutomatically !== 'boolean' &&
+      showInAppMessagesAutomatically.display === 'deferred'
+        ? {
+            triggerDisplayMessages: (messages: Partial<InAppMessage>[]) => {
+              parsedMessages = messages as InAppMessage[];
+
+              return paintMessageToDOM();
+            }
+          }
+        : {};
+
     return {
       request: (): IterablePromise<InAppMessageResponse> =>
         baseIterableRequest<InAppMessageResponse>({
@@ -521,6 +546,21 @@ export function getInAppMessages(
             return response;
           })
           .then((response) => {
+            if (
+              typeof showInAppMessagesAutomatically !== 'boolean' &&
+              showInAppMessagesAutomatically.display === 'deferred'
+            ) {
+              /*
+                if the user passed "deferred" for the second argument to _getMessages_
+                then they're going to choose to display the in-app messages when they want
+                with the returned, _triggerDisplayMessages_ function. So early return here
+                with no filtering or sorting.
+              */
+              return response;
+            }
+
+            /* otherwise, they're choosing to show the messages automatically */
+
             /* 
               if the user passed the flag to automatically paint the in-app messages
               to the DOM, start a timer and show each in-app message upon close + timer countdown
@@ -553,7 +593,8 @@ export function getInAppMessages(
       },
       resumeMessageStream: () => {
         return paintMessageToDOM();
-      }
+      },
+      ...maybeDisplayFn
     };
   }
 

src/inapp/index.ts

@@ -1,2 +1,3 @@
 export * from './inapp';
 export * from './types';
+export { filterHiddenInAppMessages, sortInAppMessages } from './utils';