feat: adding fullstory sdk package files
This commit is contained in:
Carlos
281
README.md
281
README.md
@@ -1 +1,280 @@
|
||||
# fullstory-asset-sdk
|
||||
# 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](#installation-guide)
|
||||
- [Usage Documentation](#usage-documentation)
|
||||
- [Configuration Options](#configuration-options)
|
||||
- [Implementation Examples](#implementation-examples)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Contributing Guidelines](#contributing-guidelines)
|
||||
- [Technical Details](#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`:
|
||||
|
||||
```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
|
||||
|
||||
### 1. Using the FullStory Provider in a React App
|
||||
|
||||
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 (
|
||||
<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.
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```jsx
|
||||
<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.
|
||||
|
||||
```js
|
||||
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`:
|
||||
|
||||
```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:
|
||||
|
||||
```js
|
||||
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:
|
||||
```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
|
||||
|
||||
### 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:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/CarGDev/fullstory-asset-sdk.git
|
||||
cd fullstory-asset-sdk
|
||||
npm install
|
||||
```
|
||||
|
||||
To run tests:
|
||||
|
||||
```sh
|
||||
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](https://github.com/CarGDev/fullstory-asset-sdk/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.
|
||||
```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](https://github.com/CarGDev/fullstory-asset-sdk)**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user