Added crossOrigin, onLoad, and onLoadFailed config options

.changeset/nice-dryers-begin.md

@@ -0,0 +1,5 @@
+---
+'react-use-intercom': minor
+---
+
+Added crossOrigin, onLoad, and onLoadFailed config options

README.md

@@ -91,6 +91,9 @@ Place the `IntercomProvider` as high as possible in your application. This will
 | 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    |         |
 | autoBootProps | IntercomProps | Pass properties to `boot` method when `autoBoot` is `true` | false    |         |
+| crossOrigin         | string           | `crossOrigin` attribute value to pass to `<script>` tag that loads the messenger        | false    |         |
+| onLoad              | () => void       | triggered when the Messenger script has been loaded successfully                        | false    |         |
+| onLoadFailed        | () => void       | triggered when the Messenger script has failed to load                                  | false    |         |
 
 #### Example
 ```ts
@@ -295,3 +298,9 @@ These props are `JavaScript` 'friendly', so [camelCase](https://en.wikipedia.org
 Since [v1.2.0](https://github.com/devrnt/react-use-intercom/releases/tag/v1.2.0) it's possible to delay this initialisation by passing `initializeDelay` in `<IntercomProvider />` (it's in milliseconds). However most of the users won't need to mess with this.
 
 For reference see https://github.com/devrnt/react-use-intercom/pull/236 and https://forum.intercom.com/s/question/0D52G00004WxWLs/can-i-delay-loading-intercom-on-my-site-to-reduce-the-js-load
+
+### Detect a broken Messenger
+
+There can be various reasons why the Messenger script has failed to load, e.g. network issues, Intercom downtime, firewall issues, or browser extensions like tracking blockers.
+
+By using the `onLoadFailed` callback it's possible to detect when that happens and provide the user with alternative means of customer support.

apps/playground/cypress/e2e/crossOrigin.ts

@@ -0,0 +1,12 @@
+/// <reference types="cypress" />
+
+describe('use crossOrigin', () => {
+  it('should add attribute to script tag', () => {
+    cy.visit('/useIntercomWithCrossOrigin');
+
+    cy.document()
+      .get('head script')
+      .should('have.attr', 'crossOrigin')
+      .should('eq', 'anonymous');
+  });
+});

apps/playground/cypress/e2e/loadCallbacks.ts

@@ -0,0 +1,29 @@
+/// <reference types="cypress" />
+
+describe('onLoad/onLoadFailed', () => {
+  it('should call onLoad when successful', () => {
+    cy.intercept('https://widget.intercom.io/widget/jcabc7e3', (request) => {
+      request.continue((response) => {
+        response.headers['cache-control'] = 'no-cache';
+      });
+    });
+
+    cy.visit('/useIntercomWithLoadCallbacks');
+
+    cy.get('[data-cy=call]').should(($p) =>
+      expect($p).to.have.text('onLoad was called!'),
+    );
+  });
+
+  it('should call onLoadFailed when not successful', () => {
+    cy.intercept('https://widget.intercom.io/widget/jcabc7e3', {
+      forceNetworkError: true,
+    });
+
+    cy.visit('/useIntercomWithLoadCallbacks');
+
+    cy.get('[data-cy=call]').should(($p) =>
+      expect($p).to.have.text('onLoadFailed was called!'),
+    );
+  });
+});

apps/playground/src/app.tsx

@@ -9,7 +9,9 @@ import {
   ProviderPage,
   UseIntercomPage,
   UseIntercomTourPage,
+  UseIntercomWithCrossOrigin,
   UseIntercomWithDelay,
+  UseIntercomWithLoadCallbacks,
 } from './modules';
 import { Page, Style } from './modules/common';
 
@@ -52,6 +54,14 @@ const App = () => {
           />
           <Route path="/useIntercom" component={UseIntercomPage} />
           <Route path="/useIntercomTour" component={UseIntercomTourPage} />
+          <Route
+            path="/useIntercomWithCrossOrigin"
+            component={UseIntercomWithCrossOrigin}
+          />
+          <Route
+            path="/useIntercomWithLoadCallbacks"
+            component={UseIntercomWithLoadCallbacks}
+          />
           <Route
             path="/useIntercomWithTimeout"
             component={UseIntercomWithDelay}
@@ -70,9 +80,15 @@ const App = () => {
               <Link to="/useIntercomTour">
                 <code>useIntercom with tour</code>
               </Link>
+              <Link to="/useIntercomWithCrossOrigin">
+                <code>useIntercom with crossOrigin</code>
+              </Link>
               <Link to="/useIntercomWithTimeout">
                 <code>useIntercom with delayed boot</code>
               </Link>
+              <Link to="/useIntercomWithLoadCallbacks">
+                <code>useIntercom with load callbacks</code>
+              </Link>
             </Navigation>
           </Route>
         </Router>

apps/playground/src/modules/useIntercom/index.ts

@@ -1,3 +1,5 @@
 export { default as UseIntercomPage } from './useIntercom';
 export { default as UseIntercomTourPage } from './useIntercomTour';
+export { default as UseIntercomWithCrossOrigin } from './useIntercomWithCrossOrigin';
 export { default as UseIntercomWithDelay } from './useIntercomWithDelay';
+export { default as UseIntercomWithLoadCallbacks } from './useIntercomWithLoadCallbacks';

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

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { IntercomProvider } from 'react-use-intercom';
+import styled from 'styled-components';
+
+const Grid = styled.div`
+  display: grid;
+  grid-template-columns: repeat(1, 1fr);
+  width: 100%;
+`;
+
+const Item = styled.div`
+  display: grid;
+  grid-template-rows: min-content;
+
+  &::after {
+    content: '';
+    margin: 2rem 0 1.5rem;
+    border-bottom: 2px solid var(--grey);
+    width: 100%;
+  }
+`;
+
+const RawUseIntercomPage = () => {
+  return (
+    <Grid>
+      <Item>
+        <p>
+          Intercom will be initialized with{' '}
+          <code>crossOrigin: "anonymous"</code> (and autobooted)
+        </p>
+      </Item>
+    </Grid>
+  );
+};
+
+const UseIntercomWithCrossOriginPage = () => {
+  return (
+    <IntercomProvider appId="jcabc7e3" autoBoot crossOrigin="anonymous">
+      <RawUseIntercomPage />
+    </IntercomProvider>
+  );
+};
+
+export default UseIntercomWithCrossOriginPage;

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

@@ -0,0 +1,53 @@
+import { useState } from 'react';
+import * as React from 'react';
+import { IntercomProvider } from 'react-use-intercom';
+import styled from 'styled-components';
+
+const Grid = styled.div`
+  display: grid;
+  grid-template-columns: repeat(1, 1fr);
+  width: 100%;
+`;
+
+const Item = styled.div`
+  display: grid;
+  grid-template-rows: min-content;
+
+  &::after {
+    content: '';
+    margin: 2rem 0 1.5rem;
+    border-bottom: 2px solid var(--grey);
+    width: 100%;
+  }
+`;
+
+const RawUseIntercomPage = ({ call }: { call: string | undefined }) => {
+  return (
+    <Grid>
+      <Item>
+        <p>
+          The Intercom Messenger script will be loaded and{' '}
+          <code>onLoad/onLoadFailed</code> be called
+        </p>
+        <p data-cy="call">{call ?? 'Waiting…'}</p>
+      </Item>
+    </Grid>
+  );
+};
+
+const UseIntercomWithLoadCallbacks = () => {
+  const [call, setCall] = useState<string>();
+
+  return (
+    <IntercomProvider
+      appId="jcabc7e3"
+      autoBoot
+      onLoad={() => setCall('onLoad was called!')}
+      onLoadFailed={() => setCall('onLoadFailed was called!')}
+    >
+      <RawUseIntercomPage call={call} />
+    </IntercomProvider>
+  );
+};
+
+export default UseIntercomWithLoadCallbacks;

packages/react-use-intercom/src/initialize.ts

@@ -4,10 +4,19 @@
  *
  * @param appId - Intercom app id
  * @param [timeout=0] - Amount of milliseconds that the initialization should be delayed, defaults to 0
+ * @param [crossOrigin=undefined] - `crossOrigin` attribute value to use for the `<script>` tag, defaults to `undefined`
+ * @param [onLoad=undefined] - Called when the Messenger script has been loaded successfully, defaults to `undefined`.
+ * @param [onLoadFailed=undefined] - Called when the Messenger script has failed to load, defaults to `undefined`.
  *
  * @see {@link https://developers.intercom.com/installing-intercom/docs/basic-javascript}
  */
-const initialize = (appId: string, timeout = 0) => {
+const initialize = (
+  appId: string,
+  timeout = 0,
+  crossOrigin: string | undefined = undefined,
+  onLoad: () => void = undefined,
+  onLoadFailed: () => void = undefined,
+) => {
   var w = window;
   var ic = w.Intercom;
   if (typeof ic === 'function') {
@@ -26,9 +35,21 @@ const initialize = (appId: string, timeout = 0) => {
     var l = function () {
       setTimeout(function () {
         var s = d.createElement('script');
+        s.crossOrigin = crossOrigin;
         s.type = 'text/javascript';
         s.async = true;
         s.src = 'https://widget.intercom.io/widget/' + appId;
+        if (onLoad) {
+          s.addEventListener('load', () => {
+            onLoad();
+          });
+        }
+        if (onLoadFailed) {
+          s.addEventListener('error', () => {
+            // No need to pass any information from the ErrorEvent because it will contain no information about the error.
+            onLoadFailed();
+          });
+        }
         var x = d.getElementsByTagName('script')[0];
         x.parentNode.insertBefore(s, x);
       }, timeout);

packages/react-use-intercom/src/provider.tsx

@@ -21,7 +21,10 @@ export const IntercomProvider: React.FC<
   autoBoot = false,
   autoBootProps,
   children,
+  crossOrigin,
   onHide,
+  onLoad,
+  onLoadFailed,
   onShow,
   onUnreadCountChange,
   onUserEmailSupplied,
@@ -84,7 +87,7 @@ export const IntercomProvider: React.FC<
   }, [onShow, setIsOpen]);
 
   if (!isSSR && shouldInitialize && !isInitialized.current) {
-    initialize(appId, initializeDelay);
+    initialize(appId, initializeDelay, crossOrigin, onLoad, onLoadFailed);
 
     // attach listeners
     IntercomAPI('onHide', onHideWrapper);

packages/react-use-intercom/src/types.ts

@@ -474,10 +474,29 @@ export type IntercomProviderProps = {
    * @remarks if `true`, 'boot' does not need to be called manually
    * */
   autoBoot?: boolean;
+  /**
+   * The optional `crossOrigin` attribute value to use for the `<script>` tag that loads the messenger.
+   *
+   * Use `crossOrigin: "anonymous"` to have errors thrown by the Messenger contain all information (file name, line, message, etc.).
+   * This is useful for error logging and following up with Intercom's own tech support.
+   *
+   * Note that this doesn't work for errors thrown because the Messenger script file has failed to load.
+   */
+  crossOrigin?: 'anonymous' | 'use-credentials' | '' | undefined;
   /**
    * When we hide the messenger, you can hook into the event. This requires a function argument.
    */
   onHide?: () => void;
+  /**
+   * Called when the Messenger script file has been loaded successfully.
+   */
+  onLoad?: () => void;
+  /**
+   * Called when the Messenger script file has failed to load.
+   *
+   * You can use this to let the customer know the support chat is unavailable and provide an alternative communication method.
+   */
+  onLoadFailed?: () => void;
   /**
    * When we show the messenger, you can hook into the event. This requires a function argument.
    */