@fullstory/browser 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.6.1
+
+- Fix a TypeScript type issue with the `readyCallback` API (#144)
+- Add a RELEASING doc (#143)
+## 1.6.0
+
+- Add a `readyCallback` parameter to the `init` function (#140)
+- Add an `isInitialized` API (#130)
+- Automated dependency updates
+
+## 1.5.1
+
+- Updating README to include `host` and `script` configuration options
+
 ## 1.5.0
 
 - Adding the `setVars` API function

package/README.md

@@ -1,6 +1,6 @@
 # FullStory Browser SDK
 
-[![CircleCI](https://circleci.com/gh/fullstorydev/fullstory-browser-sdk.svg?style=svg)](https://circleci.com/gh/fullstorydev/fullstory-browser-sdk)
+[![CircleCI](https://circleci.com/gh/fullstorydev/fullstory-browser-sdk.svg?style=svg)](https://circleci.com/gh/fullstorydev/fullstory-browser-sdk) [![npm (scoped)](https://img.shields.io/npm/v/@fullstory/browser)](https://www.npmjs.com/package/@fullstory/browser)
 
 FullStory's browser SDK lets you manage FullStory recording on your site as well as retrieve deep links to session replays and send your own custom events. More information about the FullStory API can be found at https://developer.fullstory.com.
 
@@ -20,7 +20,7 @@ yarn add @fullstory/browser
 
 ## Initialize the SDK
 
-Call the `init()` function with options as soon as you can in your website startup process.
+Call the `init()` function with options as soon as you can in your website startup process. Calling init after successful initialization will trigger console warnings - if you need to programmatically check if FullStory has been initialized at some point in your code, you can call `isInitialized()`.
 
 ### Configuration Options
 
@@ -28,11 +28,21 @@ The only required option is `orgId`, all others are optional.
 
 *  `orgId` -  Sets your FullStory Org Id. Find out how to get your Org Id [here](https://help.fullstory.com/hc/en-us/articles/360047075853).
 *  `debug` - When set to `true`, enables FullStory debug messages; defaults to `false`.
+*  `host` - The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`.
+*  `script` - FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com`.
 * `namespace` - Sets the global identifier for FullStory when conflicts with `FS` arise; see [help](https://help.fullstory.com/hc/en-us/articles/360020624694-What-if-the-identifier-FS-is-used-by-another-script-on-my-site-).
 * `recordCrossDomainIFrames` - Defaults to `false`. FullStory can record cross-domain iFrames if: 1. The FullStory Browser SDK is running in the cross-domain iFrame and 2. `recordCrossDomainIFrames` is set to `true` in the cross-domain iFrame and 3. The FullStory Browser SDK is running in the parent page of the cross-domain iFrame. Click [here](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) for a detailed explanation of what "cross-domain" means. Before using, you should understand the security implications, and configure your [Content Security Policy](https://www.html5rocks.com/en/tutorials/security/content-security-policy/) (CSP) HTTP headers accordingly - specifically the frame-ancestors directive. Failure to configure your CSP headers while using this setting can bypass IFrames security protections that are included in modern browsers. More information about cross-domain iFrame recording can be found on our [Knowledge Base](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#2-the-outer-page-is-running-fullstory-and-you-have-iframes-runni). Note: the `recordCrossDomainIFrames` parameter is the same as the `window['_fs_run_in_iframe']` referenced in the KB article.
 * `recordOnlyThisIFrame` - When set to `true`, this tells FullStory that the IFrame is the "root" of the recording and should be its own session; defaults to `false`. Use this when your app is embedded in an IFrame on a site not running FullStory or when the site *is* running FullStory, but you want your content sent to a different FullStory org.
 * `devMode` - Set to `true` if you want to deactivate FullStory in your development environment. When set to `true`, FullStory will shutdown recording and all subsequent SDK method calls will be no-ops. At the time `init` is called with `devMode: true`, a single `event` call will be sent to FullStory to indicate that the SDK is in `devMode`; this is to help trouble-shoot the case that the SDK was accidentally set to `devMode: true` in a production environment. Additionally, any calls to SDK methods will `console.warn` that FullStory is in `devMode`. Defaults to `false`.
 
+### Ready Callback
+
+The `init` function also accepts an optional `readyCallback` argument. If you provide a function, it will be invoked when the FullStory session has started. Your callback will be called with one parameter: an object containing information about the session. Currently the only property is `sessionUrl`, which is a string containing the URL to the session.
+
+```javascript
+FullStory.init({ orgId, ({ sessionUrl }) => console.log(`Started session: ${sessionUrl}`));
+```
+
 ### Initialization Examples
 
 #### React

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * - debug: Debug mode with extra browser console logging.
  * - host: The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`.
  * - script: FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com`.
- * - recordCrossDomainIFrames: FullStory can record cross-domain iFrames. Defaults to `false`. Certain limitations apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G333PYKPGZ4B42WDBV3YKV). 
+ * - recordCrossDomainIFrames: FullStory can record cross-domain iFrames. Defaults to `false`. Certain limitations apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G333PYKPGZ4B42WDBV3YKV).
  * - recordOnlyThisIFrame: FullStory can record the iFrame as its own unique session. Defaults to `false`. Additional conditions apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G33B40Q2TPQA8MA7SF8Y5P).
  * - devMode: In dev mode FullStory won't record sessions. Any calls to SDK methods will `console.warn` that FullStory is in `devMode`. Defaults to `false`.
  */
@@ -31,12 +31,26 @@ type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 
 type VarScope = 'page';
 
+/**
+ * A callback that will be invoked when FullStory has begun a session.
+ *
+ * `sessionUrl` contains the URL to the current session.
+ */
+type ReadyCallback = (data: { sessionUrl: string }) => void;
+
 // API functions that are available as soon as the snippet has executed.
 export function anonymize(): void;
 export function consent(userConsents?: boolean): void;
 export function event(eventName: string, eventProperties: { [key: string]: any }): void;
 export function identify(uid: string, customVars?: UserVars): void;
-export function init(options: SnippetOptions): void;
+/**
+ * Initialize FullStory.
+ *
+ * @param options Options to pass to the snippet.
+ * @param readyCallback If provided, a callback that will be invoked when the FullStory session has begun.
+ */
+export function init(options: SnippetOptions, readyCallback?: ReadyCallback): void;
+export function isInitialized(): boolean;
 export function log(level: LogLevel, msg: string): void;
 export function log(msg: string): void;
 export function restart(): void;

package/dist/index.esm.js

@@ -157,7 +157,7 @@ var restart = guard('restart');
 var anonymize = guard('anonymize');
 var setVars = guard('setVars');
 
-var _init = function _init(options) {
+var _init = function _init(options, readyCallback) {
   if (fs()) {
     console.warn('The FullStory snippet has already been defined elsewhere (likely in the <head> element)');
     return;
@@ -173,6 +173,13 @@ var _init = function _init(options) {
 
   snippet(options);
 
+  if (readyCallback) {
+    fs()('observe', {
+      type: 'start',
+      callback: readyCallback
+    });
+  }
+
   if (options.devMode === true) {
     var message = 'FullStory was initialized in devMode and will stop recording';
     event('FullStory Dev Mode', {
@@ -197,5 +204,8 @@ var initOnce = function initOnce(fn, message) {
 };
 
 var init = initOnce(_init, 'FullStory init has already been called once, additional invocations are ignored');
+var isInitialized = function isInitialized() {
+  return !!window._fs_initialized;
+};
 
-export { anonymize, consent, event, getCurrentSessionURL, identify, init, log, restart, setUserVars, setVars, shutdown };
+export { anonymize, consent, event, getCurrentSessionURL, identify, init, isInitialized, log, restart, setUserVars, setVars, shutdown };

package/dist/index.js

@@ -161,7 +161,7 @@ var restart = guard('restart');
 var anonymize = guard('anonymize');
 var setVars = guard('setVars');
 
-var _init = function _init(options) {
+var _init = function _init(options, readyCallback) {
   if (fs()) {
     console.warn('The FullStory snippet has already been defined elsewhere (likely in the <head> element)');
     return;
@@ -177,6 +177,13 @@ var _init = function _init(options) {
 
   snippet(options);
 
+  if (readyCallback) {
+    fs()('observe', {
+      type: 'start',
+      callback: readyCallback
+    });
+  }
+
   if (options.devMode === true) {
     var message = 'FullStory was initialized in devMode and will stop recording';
     event('FullStory Dev Mode', {
@@ -201,6 +208,9 @@ var initOnce = function initOnce(fn, message) {
 };
 
 var init = initOnce(_init, 'FullStory init has already been called once, additional invocations are ignored');
+var isInitialized = function isInitialized() {
+  return !!window._fs_initialized;
+};
 
 exports.anonymize = anonymize;
 exports.consent = consent;
@@ -208,6 +218,7 @@ exports.event = event;
 exports.getCurrentSessionURL = getCurrentSessionURL;
 exports.identify = identify;
 exports.init = init;
+exports.isInitialized = isInitialized;
 exports.log = log;
 exports.restart = restart;
 exports.setUserVars = setUserVars;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstory/browser",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "The official FullStory browser SDK",
   "repository": "git://github.com/fullstorydev/fullstory-browser-sdk.git",
   "homepage": "https://github.com/fullstorydev/fullstory-browser-sdk",

package/src/index.d.ts

@@ -6,7 +6,7 @@
  * - debug: Debug mode with extra browser console logging.
  * - host: The recording server host domain. Can be set to direct recorded events to a proxy that you host. Defaults to `fullstory.com`.
  * - script: FullStory script host domain. FullStory hosts the `fs.js` recording script on a CDN, but you can choose to host a copy yourself. Defaults to `edge.fullstory.com`.
- * - recordCrossDomainIFrames: FullStory can record cross-domain iFrames. Defaults to `false`. Certain limitations apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G333PYKPGZ4B42WDBV3YKV). 
+ * - recordCrossDomainIFrames: FullStory can record cross-domain iFrames. Defaults to `false`. Certain limitations apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G333PYKPGZ4B42WDBV3YKV).
  * - recordOnlyThisIFrame: FullStory can record the iFrame as its own unique session. Defaults to `false`. Additional conditions apply and can be found [here](https://help.fullstory.com/hc/en-us/articles/360020622514-Can-FullStory-capture-content-that-is-presented-in-iframes-#h_01F1G33B40Q2TPQA8MA7SF8Y5P).
  * - devMode: In dev mode FullStory won't record sessions. Any calls to SDK methods will `console.warn` that FullStory is in `devMode`. Defaults to `false`.
  */
@@ -31,12 +31,26 @@ type LogLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 
 type VarScope = 'page';
 
+/**
+ * A callback that will be invoked when FullStory has begun a session.
+ *
+ * `sessionUrl` contains the URL to the current session.
+ */
+type ReadyCallback = (data: { sessionUrl: string }) => void;
+
 // API functions that are available as soon as the snippet has executed.
 export function anonymize(): void;
 export function consent(userConsents?: boolean): void;
 export function event(eventName: string, eventProperties: { [key: string]: any }): void;
 export function identify(uid: string, customVars?: UserVars): void;
-export function init(options: SnippetOptions): void;
+/**
+ * Initialize FullStory.
+ *
+ * @param options Options to pass to the snippet.
+ * @param readyCallback If provided, a callback that will be invoked when the FullStory session has begun.
+ */
+export function init(options: SnippetOptions, readyCallback?: ReadyCallback): void;
+export function isInitialized(): boolean;
 export function log(level: LogLevel, msg: string): void;
 export function log(msg: string): void;
 export function restart(): void;

package/src/index.js

@@ -39,7 +39,7 @@ export const restart = guard('restart');
 export const anonymize = guard('anonymize');
 export const setVars = guard('setVars');
 
-const _init = (options) => {
+const _init = (options, readyCallback) => {
   if (fs()) {
     // eslint-disable-next-line no-console
     console.warn('The FullStory snippet has already been defined elsewhere (likely in the <head> element)');
@@ -58,6 +58,10 @@ const _init = (options) => {
 
   snippet(options);
 
+  if (readyCallback) {
+    fs()('observe', { type: 'start', callback: readyCallback });
+  }
+
   if (options.devMode === true) {
     const message = 'FullStory was initialized in devMode and will stop recording';
     event('FullStory Dev Mode', {
@@ -80,3 +84,6 @@ const initOnce = (fn, message) => (...args) => {
 };
 
 export const init = initOnce(_init, 'FullStory init has already been called once, additional invocations are ignored');
+
+// normalize undefined into boolean
+export const isInitialized = () => !!window._fs_initialized;