@percy.ai/sdk
v2.0.2
Published
PercySDK is a TypeScript-based SDK that allows sending signals from a frontend application to an endpoint using a POST request. It is designed to be configurable for different environments and follows good practices for front-end SDKs, such as using worke
Downloads
6
Readme
PercySDK
PercySDK is a TypeScript-based SDK that allows sending signals from a frontend application to an endpoint using a POST request. It is designed to be configurable for different environments and follows good practices for front-end SDKs, such as using workers to avoid blocking UI threads and implementing retries.
Installation
To install PercySDK, use pnpm, npm or yarn:
npm install percy-sdkor
yarn add percy-sdkUsage
Frontend Application
To use PercySDK in your frontend application, import and instantiate it with the necessary options:
import PercySDK from "percy-sdk";
const percySDK = new PercySDK({
environment: "production",
clientKey: "YOUR_CLIENT_KEY",
});
const signal: Signal = {
id: "unique-signal-id",
signal: "avm_view",
body: {
meta: "data",
},
};
percySDK.sendSignal(signal);HTML based Website
To use PercySDK in your website, import and instantiate it with the necessary options:
<body>
<script src="https://cdn.jsdelivr.net/npm/@percy.ai/sdk@latest/dist/umd/percy-sdk.min.js></script>
<script>
const percySDK = new PercySDK.default({
clientKey: "YOUR_CLIENT_KEY",
});
const percySnapshotButton = document.getElementById("percySnapshotButton");
percySnapshotButton.addEventListener("click", async () => {
percySDK.sendSignal({
id: "unique-signal-id",
signal: "avm_view",
body: {
meta: "data",
},
});
});
</script>
</body>Configuration
The PercySDK constructor accepts an options object with the following properties:
clientKey(required): The Client key used for authentication when sending signals to the endpoint.environment(optional): Specifies the environment. It can be either'production'or'development'. Defaults to 'production'.maxRetries(optional): The maximum number of retries to attempt if a request fails. Defaults to 3.retryDelay(optional): The delay (in milliseconds) between retries. Defaults to 1000.
Signal Interface
The Signal interface represents the structure of a signal that can be sent using PercySDK. It has the following properties:
id(required): A unique identifier for the signal.topic(required): The topic or category of the signal.body(required): The payload data of the signal.
Sending Signals
To send a signal using PercySDK, create a Signal object and pass it to the sendSignal method:
const signal: Signal = {
id: "unique-signal-id",
signal: "signal-topic",
body: {
// Signal data object
},
};
percySDK.sendSignal(signal);The sendSignal method posts a message to the worker with the signal data and SDK configuration options. The worker then sends the signal to the endpoint using a POST request with the specified headers and body.
Error Handling and Retries
PercySDK implements error handling and retries to ensure reliable signal delivery. If a request fails, the SDK will retry the request up to the specified maxRetries times with a delay of retryDelay milliseconds between each retry.
If the maximum number of retries is reached and the request still fails, the signal will be discarded, and no further attempts will be made.
Browser Support
PercySDK is compatible with modern browsers that support Web Workers and the Fetch API. It has been tested on the following browsers:
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
License
PercySDK is released under the MIT License.