Merge pull request #627 from devrnt/622-implement-new-apis

622 implement new apis

Author: devrnt

.changeset/smart-mice-occur.md

@@ -0,0 +1,5 @@
+---
+'react-use-intercom': minor
+---
+
+Extend API with `onUserEmailSupplied` event and `startSurvey` method

.github/workflows/e2e-testing.yml

@@ -38,7 +38,7 @@ jobs:
           # build playground
           # build: pnpm dev:playground
           # start playground
-          start: pnpm dev:playground
+          start: pnpm dev
           command: pnpm e2e
           # FIXME: this breaks it
           # wait-on: 'http://localhost:5173'

README.md

@@ -79,6 +79,7 @@ Place the `IntercomProvider` as high as possible in your application. This will
 | onHide              | () => void       | triggered when the Messenger hides                                                      | false    |         |
 | onShow              | () => void       | triggered when the Messenger shows                                                      | false    |         |
 | onUnreadCountChange | (number) => void | triggered when the current number of unread messages changes                            | false    |         |
+| onUserEmailSupplied | () => void | triggered when a visitor enters their email into the Messenger                         | false    |         |
 | shouldInitialize    | boolean | indicates if the Intercom should be initialized. Can be used in multistaged environment          | false    | true    |
 | apiBase    | string | If you need to route your Messenger requests through a different endpoint than the default. Generally speaking, this is not needed.<br/> Format: `https://${INTERCOM_APP_ID}.intercom-messenger.com` (See: [https://github.com/devrnt/react-use-intercom/pull/96](https://github.com/devrnt/react-use-intercom/pull/96))         | false    |         |
 | initializeDelay | number | Indicates if the intercom initialization should be delayed, delay is in ms, defaults to 0. See https://github.com/devrnt/react-use-intercom/pull/236 | false    |         |
@@ -95,13 +96,17 @@ const App = () => {
     console.log('Intercom has a new unread message');
     setUnreadMessagesCount(amount);
   };
+  const onUserEmailSupplied = () => {
+    console.log('Visitor has entered email');
+  };
 
   return (
     <IntercomProvider
       appId={INTERCOM_APP_ID}
       onHide={onHide}
       onShow={onShow}
       onUnreadCountChange={onUnreadCountChange}
+      onUserEmailSupplied={onUserEmailSupplied}
       autoBoot
     >
       <p>Hi there, I am a child of the IntercomProvider</p>
@@ -134,6 +139,7 @@ Used to retrieve all methods bundled with Intercom. These are based on the offic
 | startTour       | (tourId: number) => void                   | starts a tour based on the `tourId`                                                                                                 |
 | trackEvent      | (event: string, metaData?: object) => void | submits an `event` with optional `metaData`      
 | showArticle      | (articleId: string) => void | opens the Messenger with the specified article by `articleId`
+| startSurvey      | (surveyId: number) => void | Trigger a survey in the Messenger by `surveyId`
 
 #### Example
 ```javascript
@@ -162,7 +168,8 @@ const HomePage = () => {
     getVisitorId,
     startTour,
     trackEvent,
-    showArticle
+    showArticle,
+    startSurvey
   } = useIntercom();
 
   const bootWithProps = () => boot({ name: 'Russo' });
@@ -177,6 +184,7 @@ const HomePage = () => {
       name: 'Russo',
     });
   const handleShowArticle = () => showArticle(123456);
+  const handleStartSurvey = () => startSurvey(123456);
 
   return (
     <>
@@ -200,6 +208,7 @@ const HomePage = () => {
         Track event with metadata
       </button>
       <button onClick={handleShowArticle}>Open article in Messenger</button>
+      <button onClick={handleStartSurvey}>Start survey in Messenger</button>
     </>
   );
 };

apps/playground/src/modules/provider/provider.tsx

@@ -1,5 +1,4 @@
 import * as React from 'react';
-
 import { IntercomProvider } from 'react-use-intercom';
 
 const Provider = () => {

apps/playground/src/modules/provider/providerEvents.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
+import { IntercomProvider, useIntercom } from 'react-use-intercom';
 import styled from 'styled-components';
 
-import { IntercomProvider, useIntercom } from 'react-use-intercom';
 import { Button } from '../common';
 
 const Grid = styled.div`
@@ -25,11 +25,13 @@ const Item = styled.div`
 type RawProviderEventsProps = {
   onShowText: string;
   onHideText: string;
+  onUserEmailSuppliedText: string;
 };
 
 const RawProviderEvents = ({
   onShowText,
   onHideText,
+  onUserEmailSuppliedText,
 }: RawProviderEventsProps) => {
   const { boot, show, hide } = useIntercom();
 
@@ -38,6 +40,7 @@ const RawProviderEvents = ({
       <p>Intercom children</p>
       <p data-cy="onShowText">{onShowText}</p>
       <p data-cy="onHideText">{onHideText}</p>
+      <p data-cy="onUserEmailSuppliedText">{onUserEmailSuppliedText}</p>
 
       <Grid>
         <Item>
@@ -61,13 +64,26 @@ const RawProviderEvents = ({
 const ProviderEvents = () => {
   const [onShowText, setOnShowText] = React.useState('default');
   const [onHideText, setHideText] = React.useState('default');
+  const [onUserEmailSuppliedText, setOnUserEmailSupplied] =
+    React.useState('default');
 
   const onShow = React.useCallback(() => setOnShowText('show was called'), []);
   const onHide = React.useCallback(() => setHideText('hide was called'), []);
+  const onUserEmailSupplied = () =>
+    setOnUserEmailSupplied('on user email supplied was called');
 
   return (
-    <IntercomProvider appId="jcabc7e3" onShow={onShow} onHide={onHide}>
-      <RawProviderEvents onShowText={onShowText} onHideText={onHideText} />
+    <IntercomProvider
+      appId="jcabc7e3"
+      onShow={onShow}
+      onHide={onHide}
+      onUserEmailSupplied={onUserEmailSupplied}
+    >
+      <RawProviderEvents
+        onUserEmailSuppliedText={onUserEmailSuppliedText}
+        onShowText={onShowText}
+        onHideText={onHideText}
+      />
     </IntercomProvider>
   );
 };

apps/playground/src/modules/useIntercom/useIntercom.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
+import { IntercomProvider, useIntercom } from 'react-use-intercom';
 import styled from 'styled-components';
 
-import { IntercomProvider, useIntercom } from 'react-use-intercom';
 import { Button } from '../common';
 
 const Grid = styled.div`
@@ -23,6 +23,8 @@ const Item = styled.div`
 `;
 
 const RawUseIntercomPage = () => {
+  const [visitorId, setVisitorId] = React.useState<string | null>(null);
+
   const {
     boot,
     shutdown,
@@ -35,12 +37,14 @@ const RawUseIntercomPage = () => {
     getVisitorId,
     trackEvent,
     showArticle,
+    startSurvey,
   } = useIntercom();
   const handleBoot = React.useCallback(() => boot(), [boot]);
 
-  const handleSeededBoot = React.useCallback(() => boot({ name: 'Russo' }), [
-    boot,
-  ]);
+  const handleSeededBoot = React.useCallback(
+    () => boot({ name: 'Russo' }),
+    [boot],
+  );
 
   const handleExtendedSeededBoot = React.useCallback(
     () =>
@@ -111,9 +115,10 @@ const RawUseIntercomPage = () => {
     update({ name: 'ponas' });
   }, [update]);
 
-  const handleNewMessages = React.useCallback(() => showNewMessage(), [
-    showNewMessage,
-  ]);
+  const handleNewMessages = React.useCallback(
+    () => showNewMessage(),
+    [showNewMessage],
+  );
 
   const handleNewMessagesWithContent = React.useCallback(
     () => showNewMessage('pre-definded-content'),
@@ -137,7 +142,7 @@ const RawUseIntercomPage = () => {
     showArticle(4013997);
   }, [showArticle]);
 
-  const [visitorId, setVisitorId] = React.useState<string | null>(null);
+  const handleStartSurvey = () => startSurvey(29938254);
 
   return (
     <Grid>
@@ -240,6 +245,7 @@ const RawUseIntercomPage = () => {
           data-cy="visitorId"
           onClick={handleGetVisitorId}
         />
+        {visitorId ? <p data-cy="visitorIdValue">{visitorId}</p> : null}
       </Item>
       <Item>
         <p>
@@ -262,8 +268,16 @@ const RawUseIntercomPage = () => {
         </p>
         <Button label="Open article" onClick={handleShowArticle} />
       </Item>
-
-      {visitorId && <p data-cy="visitorIdValue">{visitorId}</p>}
+      <Item>
+        <p>
+          start survey with the given <code>surveyId</code>
+        </p>
+        <Button
+          data-cy="start-survey"
+          label="Start survey"
+          onClick={handleStartSurvey}
+        />
+      </Item>
     </Grid>
   );
 };

package.json

@@ -2,8 +2,7 @@
   "private": true,
   "packageManager": "pnpm@7.26.3",
   "scripts": {
-    "dev": "turbo run dev --filter=react-use-intercom --filter=playground --no-cache --continue",
-    "dev:playground": "turbo run dev --parallel --filter=playground --filter=react-use-intercom",
+    "dev": "turbo run dev --parallel --filter=playground --filter=react-use-intercom",
     "dev:examples": "turbo run dev --parallel --filter=*-example --filter=react-use-intercom",
     "test": "turbo run test",
     "build": "turbo run build",
@@ -12,6 +11,7 @@
     "lint:fix": "turbo run lint:fix",
     "clean": "turbo run clean && rm -rf node_modules",
     "e2e": "turbo run e2e --filter=react-use-intercom",
+    "e2e:open": "turbo run e2e:open --filter=react-use-intercom",
     "changeset": "changeset",
     "release": "turbo run build --filter=react-use-intercom && changeset publish"
   },
@@ -24,6 +24,6 @@
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-simple-import-sort": "^10.0.0",
     "prettier": "^2.8.3",
-    "turbo": "^1.7.3"
+    "turbo": "^1.8.3"
   }
 }

packages/react-use-intercom/README.md

@@ -79,6 +79,7 @@ Place the `IntercomProvider` as high as possible in your application. This will
 | onHide              | () => void       | triggered when the Messenger hides                                                      | false    |         |
 | onShow              | () => void       | triggered when the Messenger shows                                                      | false    |         |
 | onUnreadCountChange | (number) => void | triggered when the current number of unread messages changes                            | false    |         |
+| onUserEmailSupplied | () => void | triggered when a visitor enters their email into the Messenger                         | false    |         |
 | shouldInitialize    | boolean | indicates if the Intercom should be initialized. Can be used in multistaged environment          | false    | true    |
 | apiBase    | string | If you need to route your Messenger requests through a different endpoint than the default. Generally speaking, this is not needed.<br/> Format: `https://${INTERCOM_APP_ID}.intercom-messenger.com` (See: [https://github.com/devrnt/react-use-intercom/pull/96](https://github.com/devrnt/react-use-intercom/pull/96))         | false    |         |
 | initializeDelay | number | Indicates if the intercom initialization should be delayed, delay is in ms, defaults to 0. See https://github.com/devrnt/react-use-intercom/pull/236 | false    |         |
@@ -95,13 +96,17 @@ const App = () => {
     console.log('Intercom has a new unread message');
     setUnreadMessagesCount(amount);
   };
+  const onUserEmailSupplied = () => {
+    console.log('Visitor has entered email');
+  };
 
   return (
     <IntercomProvider
       appId={INTERCOM_APP_ID}
       onHide={onHide}
       onShow={onShow}
       onUnreadCountChange={onUnreadCountChange}
+      onUserEmailSupplied={onUserEmailSupplied}
       autoBoot
     >
       <p>Hi there, I am a child of the IntercomProvider</p>
@@ -134,6 +139,7 @@ Used to retrieve all methods bundled with Intercom. These are based on the offic
 | startTour       | (tourId: number) => void                   | starts a tour based on the `tourId`                                                                                                 |
 | trackEvent      | (event: string, metaData?: object) => void | submits an `event` with optional `metaData`      
 | showArticle      | (articleId: string) => void | opens the Messenger with the specified article by `articleId`
+| startSurvey      | (surveyId: number) => void | Trigger a survey in the Messenger by `surveyId`
 
 #### Example
 ```javascript
@@ -162,7 +168,8 @@ const HomePage = () => {
     getVisitorId,
     startTour,
     trackEvent,
-    showArticle
+    showArticle,
+    startSurvey
   } = useIntercom();
 
   const bootWithProps = () => boot({ name: 'Russo' });
@@ -177,6 +184,7 @@ const HomePage = () => {
       name: 'Russo',
     });
   const handleShowArticle = () => showArticle(123456);
+  const handleStartSurvey = () => startSurvey(123456);
 
   return (
     <>
@@ -200,6 +208,7 @@ const HomePage = () => {
         Track event with metadata
       </button>
       <button onClick={handleShowArticle}>Open article in Messenger</button>
+      <button onClick={handleStartSurvey}>Start survey in Messenger</button>
     </>
   );
 };

packages/react-use-intercom/cypress/e2e/hide.ts

@@ -1,15 +1,15 @@
 /// <reference types="cypress" />
 
 describe('hide', () => {
-  it('should show when calling `show`', () => {
+  it('should hide when calling `hide`', () => {
     cy.visit('/useIntercom');
 
     cy.get('[data-cy=boot]').click();
 
     cy.get('[data-cy=show]').click();
-    cy.get('.intercom-messenger-frame > iframe').should('be.visible');
+    cy.get('iframe[name="intercom-messenger-frame"]').should('be.visible');
 
-    cy.get('[data-cy=hide]').click({ force: true });
-    cy.get('.intercom-messenger-frame > iframe').should('not.exist');
+    cy.get('[data-cy=hide]').click();
+    cy.get('iframe[name="intercom-messenger-frame"]').should('not.be.visible');
   });
 });