@fullstory/browser 2.0.0-beta.0 → 2.0.0-beta.4

package/README.md

@@ -4,6 +4,7 @@
 
 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.
 
+> **NOTE:** this is the documentation for version 2. For version 1 documentation, please see [@fullstory/browser@1.7.1](https://www.npmjs.com/package/@fullstory/browser/v/1.7.1).
 
 ## Install the SDK
 
@@ -18,6 +19,48 @@ npm i @fullstory/browser --save
 yarn add @fullstory/browser
 ```
 
+## Migrating to Version 2.x.x
+In version 2.x.x, `init` is a separate named export from `FullStory`. You will need to update all of your wildcard (`'*'`) imports to explicit named imports.
+
+_Version 1.x.x_
+```js
+import * as FullStory from '@fullstory/browser';
+```
+
+_Version 2.x.x_
+```js
+import { FullStory, init } from '@fullstory/browser';
+```
+
+### `init`
+You can use the named import `init` by itself:
+
+```js
+import { init } from '@fullstory/browser';
+
+init({ orgId: 'my-org-id' })
+```
+You can also rename the function for readability:
+```js
+import { init as initFullStory } from '@fullstory/browser';
+
+initFullStory({ orgId: 'my-org-id' })
+```
+
+### `FullStory`
+The `FullStory` named export is equivalent to the global `FS` object described in the [developer documentation](https://developer.fullstory.com/browser/v2/getting-started/). You can use it to make all version 2 API calls:
+```js
+import { FullStory } from '@fullstory/browser';
+
+FullStory('trackEvent', {
+  name: 'My Event',
+  properties: {
+    product: 'Sprockets',
+    quantity: 1,
+  },
+})
+```
+
 ## Initialize the SDK
 
 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()`.
@@ -35,13 +78,17 @@ The only required option is `orgId`, all others are optional.
 * `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`.
+* `startCaptureManually` - Set to `true` if you want to start capture manually using `FS('start')`. FullStory will load but wait for a call to `FS('start')` to begin capturing. See [Manually Delay Data Capture](https://developer.fullstory.com/browser/v2/auto-capture/capture-data/#manually-delay-data-capture) for more information.  Defaults to `false`.
+* `assetMapId` - Use this to set the current asset map id. See [Asset Uploading for Web](https://help.fullstory.com/hc/en-us/articles/4404129191575-Asset-Uploading-for-Web) for more information.
 
 ### 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}`));
+import { init } from '@fullstory/browser';
+
+init({ orgId }, ({ sessionUrl }) => console.log(`Started session: ${sessionUrl}`));
 ```
 
 ### Initialization Examples
@@ -53,10 +100,10 @@ import React from 'react';
 import ReactDOM from 'react-dom';
 import './index.css';
 import App from './App';
-import * as FullStory from '@fullstory/browser';
+import { init as initFullStory } from '@fullstory/browser';
 
 
-FullStory.init({ orgId: '<your org id here>' });
+initFullStory({ orgId: '<your org id here>' });
 
 ReactDOM.render(<App />, document.getElementById('root'));
 ```
@@ -65,7 +112,7 @@ ReactDOM.render(<App />, document.getElementById('root'));
 
 ```javascript
 import { Component } from '@angular/core';
-import * as FullStory from '@fullstory/browser';
+import { init as initFullStory } from '@fullstory/browser';
 import { environment } from '../environments/environment';
 
 @Component({
@@ -76,8 +123,10 @@ import { environment } from '../environments/environment';
 export class AppComponent {
 
   constructor() {
-    FullStory.init({ orgId: '<your org id here>',
-      devMode: !environment.production });
+    initFullStory({
+      orgId: '<your org id here>',
+      devMode: !environment.production,
+    });
   }
 }
 ```
@@ -87,9 +136,9 @@ export class AppComponent {
 ```javascript
 import Vue from 'vue';
 import App from './App.vue';
-import * as FullStory from '@fullstory/browser';
+import { init as initFullStory, FullStory } from '@fullstory/browser';
 
-FullStory.init({ orgId: '<your org id here>' });
+initFullStory({ orgId: '<your org id here>' });
 Vue.prototype.$FullStory = FullStory;
 
 new Vue({
@@ -100,11 +149,11 @@ new Vue({
 #### Vue 3
 
 ```javascript
-import { createApp } from 'vue'
-import App from './App.vue'
-import * as FullStory from '@fullstory/browser';
+import { createApp } from 'vue';
+import App from './App.vue';
+import { init as initFullStory, FullStory } from '@fullstory/browser';
 
-FullStory.init({ orgId: '<your org id here>' });
+initFullStory({ orgId: '<your org id here>' });
 
 const app = createApp(App);
 app.config.globalProperties.$FullStory = FullStory;
@@ -113,37 +162,68 @@ app.mount('#app');
 
 ## Using the SDK
 
-Once FullStory is initialized, you can make calls to the FullStory SDK.
+Once FullStory is initialized, you can make calls to the FullStory SDK. See the [developer documentation](https://developer.fullstory.com/browser/v2/getting-started/) for more information.
 
 ### Sending custom events
 
 ```JavaScript
-FullStory.event('Subscribed', {
-  uid_str: '750948353',
-  plan_name_str: 'Professional',
-  plan_price_real: 299,
-  plan_users_int: 10,
-  days_in_trial_int: 42,
-  feature_packs: ['MAPS', 'DEV', 'DATA'],
+FullStory('trackEvent', {
+  name: 'Subscribed',
+  properties: {
+    uid: '750948353',
+    plan_name: 'Professional',
+    plan_price: 299,
+    plan_users: 10,
+    days_in_trial: 42,
+    feature_packs: ['MAPS', 'DEV', 'DATA'],
+  },
+  schema: {
+    properties: {
+      plan_users: 'int', // override default inferred "real" type with "int"
+      days_in_trial: 'int', // override default inferred "real" type with "int"
+    }
+  }
 });
 ```
 
+> **NOTE:** The inclusion of type suffixes - appending `_str` or `_int` to the end of properties - is no longer required. All custom properties are inferred on the server. To override any default inference, you can add a `schema`. See [Custom Properties](https://developer.fullstory.com/browser/v2/custom-properties/) for more information.
+
 ### Generating session replay links
 
 ```JavaScript
-const startOfPlayback = FullStory.getCurrentSessionURL();
-const playbackAtThisMomentInTime = FullStory.getCurrentSessionURL(true);
+const startOfPlayback = FullStory('getSession');
+const playbackAtThisMomentInTime = FullStory('getSession', { format: 'url.now' });
 ```
 
-### Sending custom page data
+### Sending custom user properties
 ```JavaScript
-FullStory.setVars('page', {
- pageName : 'Checkout', // what is the name of the page?
- cart_size_int : 10, // how many items were in the cart?
- used_coupon_bool : true, // was a coupon used?
+FullStory('setProperties', {
+  type: 'user',
+  properties: {
+    displayName: 'Daniel Falko',
+    email: 'daniel.falko@example.com',
+    pricing_plan: 'free',
+    popup_help: true,
+    total_spent: 14.50,
+  },
 });
 ```
-For more information on setting page vars, view the FullStory help article on [Sending custom page data to FullStory](https://help.fullstory.com/hc/en-us/articles/1500004101581-FS-setVars-API-Sending-custom-page-data-to-FullStory).
+For more information on sending custom user properties, view the FullStory help article on [Capturing custom user properties](https://help.fullstory.com/hc/en-us/articles/360020623294).
 
-#### Note
-`FullStory.setVars(<scope>, <payload>)` currently only supports a string value of "page" for the scope. Using arbitrary strings for the scope parameter will result in an Error that will be logged to the browser console or discarded, depending on whether devMode or debug is enabled.
+### Sending custom page properties
+```JavaScript
+FullStory('setProperties', {
+  type: 'page',
+  properties: {
+    pageName: 'Checkout', // what is the name of the page?
+    cart_size: 10, // how many items were in the cart?
+    used_coupon: true, // was a coupon used?
+  },
+  schema: {
+    properties: {
+      cart_size: 'int', // override default inferred "real" type with "int"
+    }
+  }
+});
+```
+For more information on setting page properties, view the FullStory help article on [Sending custom page data to FullStory](https://help.fullstory.com/hc/en-us/articles/1500004101581-FS-setVars-API-Sending-custom-page-data-to-FullStory).

package/dist/index.d.ts

@@ -14,14 +14,16 @@ import { FSApi } from '@fullstory/snippet';
  */
 export interface SnippetOptions {
     orgId: string;
-    namespace?: string;
+    assetMapId?: string;
+    cookieDomain?: string;
     debug?: boolean;
+    devMode?: boolean;
     host?: string;
-    script?: string;
-    cookieDomain?: string;
+    namespace?: string;
     recordCrossDomainIFrames?: boolean;
     recordOnlyThisIFrame?: boolean;
-    devMode?: boolean;
+    script?: string;
+    startCaptureManually?: boolean;
 }
 /**
  * A callback that will be invoked when FullStory has begun a session.
@@ -35,6 +37,8 @@ type ReadyCallback = (data: {
 }) => void;
 declare global {
     interface Window {
+        _fs_asset_map_id?: string;
+        _fs_capture_on_startup?: boolean;
         _fs_cookie_domain?: string;
         _fs_debug?: boolean;
         _fs_dev_mode?: boolean;

package/dist/index.esm.js

@@ -50,6 +50,12 @@ var _init = function (inputOptions, readyCallback) {
     if (options.recordCrossDomainIFrames) {
         window._fs_run_in_iframe = true;
     }
+    if (options.assetMapId) {
+        window._fs_asset_map_id = options.assetMapId;
+    }
+    if (options.startCaptureManually) {
+        window._fs_capture_on_startup = false;
+    }
     // record the contents of this iFrame when embedded in a parent site
     if (options.recordOnlyThisIFrame) {
         window._fs_is_outer_script = true;

package/dist/index.js

@@ -52,6 +52,12 @@ var _init = function (inputOptions, readyCallback) {
     if (options.recordCrossDomainIFrames) {
         window._fs_run_in_iframe = true;
     }
+    if (options.assetMapId) {
+        window._fs_asset_map_id = options.assetMapId;
+    }
+    if (options.startCaptureManually) {
+        window._fs_capture_on_startup = false;
+    }
     // record the contents of this iFrame when embedded in a parent site
     if (options.recordOnlyThisIFrame) {
         window._fs_is_outer_script = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstory/browser",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.4",
   "description": "The official FullStory browser SDK",
   "repository": "git://github.com/fullstorydev/fullstory-browser-sdk.git",
   "homepage": "https://github.com/fullstorydev/fullstory-browser-sdk",
@@ -26,7 +26,7 @@
     "sdk"
   ],
   "dependencies": {
-    "@fullstory/snippet": "2.0.0-beta.2"
+    "@fullstory/snippet": "2.0.0-beta.3"
   },
   "devDependencies": {
     "@babel/core": "^7.8.7",

package/src/index.ts

@@ -15,14 +15,16 @@ import { initFS, FSApi } from '@fullstory/snippet';
  */
 export interface SnippetOptions {
   orgId: string;
-  namespace?: string;
+  assetMapId?: string;
+  cookieDomain?: string;
   debug?: boolean;
+  devMode?: boolean;
   host?: string;
-  script?: string;
-  cookieDomain?: string;
+  namespace?: string;
   recordCrossDomainIFrames?: boolean;
   recordOnlyThisIFrame?: boolean;
-  devMode?: boolean;
+  script?: string;
+  startCaptureManually?: boolean;
 }
 
 /**
@@ -35,6 +37,8 @@ type ReadyCallback = (data: { sessionUrl: string, settings: Readonly<object> })
 
 declare global {
   interface Window {
+    _fs_asset_map_id?: string;
+    _fs_capture_on_startup?: boolean;
     _fs_cookie_domain?: string;
     _fs_debug?: boolean;
     _fs_dev_mode?: boolean;
@@ -79,6 +83,14 @@ const _init = (inputOptions: SnippetOptions, readyCallback?: ReadyCallback) => {
     window._fs_run_in_iframe = true;
   }
 
+  if (options.assetMapId) {
+    window._fs_asset_map_id = options.assetMapId;
+  }
+
+  if (options.startCaptureManually) {
+    window._fs_capture_on_startup = false;
+  }
+
   // record the contents of this iFrame when embedded in a parent site
   if (options.recordOnlyThisIFrame) {
     window._fs_is_outer_script = true;