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.
To install PercySDK, use pnpm, npm or yarn:
npm install percy-sdk
or
yarn add percy-sdk
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);
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>
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.
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.
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.
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.
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)
PercySDK is released under the MIT License.