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

$3

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

$3

You can install the package using npm or yarn:

``sh
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

$3

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

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

function App() {
return (
apiKey="fs-api-key-here"
assetMapPath="path/to/asset_map.json"
orgId="your-org-id"
>


My React App

);
}

export default App;
`

$3

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

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

#### CLI Options

| Option | Description |
| ----------------------- | ------------------------------------------ |
| -k, --apiKey | FullStory API Key (required) |
| -a, --assetMap | 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:

`jsx

`

---

Implementation Examples

$3

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

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

function App() {
return (
apiKey="fs-api-key-here"
assetMapPath="path/to/asset_map.json"
orgId="your-org-id"
>


My React App

);
}

export default App;
`

$3

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

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

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


);
}

export default MyApp;
`

$3

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

Example Webpack config:

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

---

Troubleshooting

$3

#### 1. FullStory Not Loading

- Ensure the API key and orgId are correct.
- Check the console for errors using:
`sh
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:

`sh
npx fullstory-uploader --help
`

or try reinstalling:

`sh
npm install -g fullstory-asset-sdk
`

---

Contributing Guidelines

$3

`
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
`

$3

To set up the project locally:

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

To run tests:

`sh
npm test
`

$3

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

$3

- 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.

$3

- API keys should never be hardcoded.
- Use environment variables to store credentials.
`sh
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