6.2 KiB
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 KeyorgId
(Required) - Your FullStory Organization IDassetMapPath
(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.
- The script (
-
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