@percy.ai/sdk NPM

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

yarn add percy-sdk

Usage

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.