FullStory Asset SDK

A lightweight SDK for integrating FullStory session tracking and asset uploading into React applications with CLI automation.

Table of Contents

• Installation Guide
• Usage Documentation
• Configuration Options
• Implementation Examples
• Troubleshooting
• Contributing Guidelines
• Technical Details

Installation Guide

Prerequisites

• Node.js >=14.0
• npm or yarn installed
• A FullStory API Key
• A valid FullStory Organization ID (orgId)

Installation

You can install the package using npm or yarn:

npm install fullstory-asset-sdk
# or
yarn add fullstory-asset-sdk

This will install:

• A React Provider Component (FullStoryProvider) for easy integration.
• A CLI tool (fullstory-uploader) for manual asset uploads.
• A cross-platform asset uploader to manage FullStory assets.

Usage Documentation

1. Using the FullStory Provider in a React App

To dynamically track sessions and manage FullStory, wrap your application with the FullStoryProvider:

import React from "react";
import { FullStoryProvider } from "fullstory-asset-sdk";

function App() {
  return (
    <FullStoryProvider
      apiKey="fs-api-key-here"
      assetMapPath="path/to/asset_map.json"
      orgId="your-org-id"
    >
      <h1>My React App</h1>
    </FullStoryProvider>
  );
}

export default App;

2. CLI Tool for Asset Uploading

The package includes a command-line interface (CLI) for manually uploading assets.

npx fullstory-uploader -k YOUR_API_KEY -a path/to/asset-map.json

CLI Options

| Option | Description | | ----------------------- | ------------------------------------------ | | -k, --apiKey <key> | FullStory API Key (required) | | -a, --assetMap <path> | Path to the Asset Map JSON file (required) |

This command uploads assets to FullStory, ensuring they are correctly mapped.

Configuration Options

When using FullStoryProvider, you need to pass:

• apiKey (Required) - Your FullStory API Key
• orgId (Required) - Your FullStory Organization ID
• assetMapPath (Required) - Path to your asset map file

Example:

<FullStoryProvider apiKey="your-api-key" orgId="your-org-id" />

Implementation Examples

1. JavaScript React Project

This package fully supports JavaScript projects even though it is written in TypeScript. You can directly use it in a JS-based React app.

import { FullStoryProvider } from "fullstory-asset-sdk";

function App() {
  return (
    <FullStoryProvider
      apiKey="fs-api-key-here"
      assetMapPath="path/to/asset_map.json"
      orgId="your-org-id"
    >
      <h1>My React App</h1>
    </FullStoryProvider>
  );
}

export default App;

2. Using with Next.js

If using Next.js, import FullStoryProvider inside _app.js:

import { FullStoryProvider } from "fullstory-asset-sdk";

function MyApp({ Component, pageProps }) {
  return (
    <FullStoryProvider
      apiKey="fs-api-key-here"
      assetMapPath="path/to/asset_map.json"
      orgId="your-org-id"
    >
      <Component {...pageProps} />
    </FullStoryProvider>
  );
}

export default MyApp;

3. Integrating with Webpack/Vite

For Webpack or Vite projects, ensure the asset uploader runs before build.

Example Webpack config:

module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      "process.env.FS_API_KEY": JSON.stringify(process.env.FS_API_KEY),
    }),
  ],
};

Troubleshooting

Common Issues

1. FullStory Not Loading

• Ensure the API key and orgId are correct.
• Check the console for errors using:

  npx fullstory-uploader -k YOUR_API_KEY -a path/to/asset-map.json

2. Asset Upload Fails

• Verify assetMapPath is correct.
• Check internet connectivity.

3. CLI Command Not Found

If the CLI tool isn’t recognized:

npx fullstory-uploader --help

or try reinstalling:

npm install -g fullstory-asset-sdk

Contributing Guidelines

Project Structure

fullstory-asset-sdk/
│── src/
│   ├── FullStoryProvider.tsx      # React Provider Component
│   ├── fullstoryUploader.ts       # Asset upload logic
│   ├── index.ts                   # Package entry point
│   ├── cli.ts                      # CLI command script
│   ├── generate-asset-map-id.js    # Cross-platform asset uploader
│── tests/                          # Jest test files
│── package.json                    # Package metadata & dependencies
│── README.md                       # Documentation

Development Setup

To set up the project locally:

git clone https://github.com/CarGDev/fullstory-asset-sdk.git
cd fullstory-asset-sdk
npm install

To run tests:

npm test

Submitting Issues

Before opening an issue:

• Check existing issues to avoid duplicates.
• Provide steps to reproduce the problem.
• Include error messages and logs.

Create an issue here: GitHub Issues

Technical Details

1. How the Package Works

• Cross-Platform Asset Uploading:

  • The script (generate-asset-map-id.js) detects OS and downloads the correct FullStory asset uploader binary.

• Dynamic Asset Map Handling:

  • The provider fetches the asset map dynamically during app initialization.

• Optimized Performance:

  • The SDK only loads FullStory when needed.
  • Avoids reloading FullStory on re-renders.

2. Security Considerations

• API keys should never be hardcoded.
• Use environment variables to store credentials.

  export FS_API_KEY="your-api-key"

Final Notes

This SDK makes FullStory integration seamless by automating:

• Session tracking
• Asset management
• React provider initialization

For any issues or contributions, check:
👉 GitHub Repository