@procore/third-party-scripts

Procore Technologies, Inc Third Party Scripts loader

We currently have

Installation

Yarn

yarn add -E @procore/third-party-scripts

Usage

What you can import from this package:

import {
  metadataEndpoint,
  ThirdPartyScripts,
  useProviderParams,
  useThirdPartyScriptsContext,
} from '@procore/third-party-scripts';

The supported third party scripts that can be loaded are as follows:

bugsnag
font
glance
googleAnalytics
launchDarkly
mindTouch
pendo
pusher
sumoLogic
userVoice

and each must be explicitly opted into to be loaded

<ThirdPartyScripts font={true}>Your app code here...</ThirdPartyScripts>

or

<ThirdPartyScripts font>Your app code here...</ThirdPartyScripts>

Dependencies

If you would like to use uservoice properly, please include or ensure that the final environment contains an element with the ID of post-ideas. If you are in the monolith or being rendered within the UI Service shell, this is already handled for you.

If you would like to have a loader experience, please supply <ThirdPartyScripts /> with a loader prop.

Breaking changes since 5.0.0 version

This change has been done in order to make third-party-scripts a tree shakable package. As part of this breaking change ThirdPartyScripts tag needs to have a scripts prop in order to load the scripts. The scripts prop is an array of supported imported scripts from third-party-scripts package. The remaining props are staying the same. The script: boolean props will get ignored.

import {
  ThirdPartyScripts,
  sumoLogic,
  font,
  bugsnag,
} from '@procore/third-party-scripts';

const scripts = [bugsnag, font];
if (myFlag) {
  scripts.push(sumoLogic);
}

<ThirdPartyScripts
  config={{
    sumoLogic: {
      endpoint: process.env.PROCORE_HYDRA_SUMO_SOURCE,
      sourceName: 'my-mfe-ui',
      sourceCategory: 'My awesome app',
    },
  }}
  metadata={customMetadata}
  scripts={scripts}
>
  <App />
</ThirdPartyScripts>;

Breaking changes from labs- version

The easy one: change the package name from @procore/labs-third-party-scripts to @procore/third-party-scripts.

The common imports from the dist directory have been moved up to the index export, and as such your imports should be merged / updated.

The LaunchDarkly client no longer evaluates allFlags by default. If you have a need for it, you can do the following to access them again:

import { useThirdPartyScriptsContext } from '@procore/third-party-scripts`;

function ExampleComponent(props) {
  const { scripts } = useThirdPartyScriptsContext();

  const allFlags = scripts?.launchDarkly?.client?.allFlags();

  return allFlags?.yourCustomFlag ? <div>Your Component A</div> : <div>Your Component B</div>;
}

How to pass a custom context or a custom attribute?

ThirdPartyScripts is already making a multiple context configuration for LaunchDarkly, which contains a standard user context. You can provide a custom attributes for the user context as well as additional contexts.

Reference: LaunchDarkly Multi-context

<ThirdPartyScripts
  config={{
   launchDarkly: {
      context: {
        user: {
         customAttribute: 'value'
        },
        organization: {
          id: '1234'
        },
        myCustomContext: {
          signature: 'private'
        }
      },
    },
  }}
  metadata={customMetadata}
  requester={request}
  scripts={scripts}
>

Local Development

For local storybook development, environment keys are necessary to successfully utilize <ThirdPartyScripts />. Follow the steps below to set up your environment correctly:

1. In this folder, create a copy of .sample.env as .env.
2. Log into your lastpass and find the note labeled core-labs third party scripts env keys.
3. Copy the entire note and paste it into your .env file.

Update the key names to include a VITE_ prefix, or match them up to the .sample.env