> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Javascript SDK

> Web SDK Integration to enable WebPush, Preferences, & In-app feed in javascript websites like React, Vue, and Next.js.

<Info>
  📘 **Upgrading major version of SDK:**

  We have changed the web SDK authentication from workspace key-secret to public key and JWT based authentication. This is done to improve security in frontend applications.

  * Refer the v1 SDK [documentation](https://github.com/suprsend/suprsend-browser-sdk/tree/main/docs)

  * For migrating to v2, follow this [guide](/docs/migration-guide-from-v1)
</Info>

This is the client JavaScript SDK used to integrate SuprSend features like Webpush, Preferences in JavaScript websites like React, Next.js, Angular, Vue.js etc.

<CardGroup cols="2">
  <Card title="NPM Link" icon="link" iconType="solid" href="https://www.npmjs.com/package/@suprsend/web-sdk" />

  <Card title="GitHub Link" icon="github" iconType="solid" href="https://github.com/suprsend/suprsend-web-sdk" />
</CardGroup>

## Installation

<CodeGroup>
  ```shell npm theme={"system"}
  npm install @suprsend/web-sdk@latest
  ```

  ```shell yarn theme={"system"}
  yarn add @suprsend/web-sdk@beta
  ```
</CodeGroup>

## Integration

<Steps>
  <Step title="Create Client">
    Create suprSendClient instance and use same instance to access all the methods of SuprSend library.&#x20;

    <CodeGroup>
      ```typescript syntax theme={"system"}
      import SuprSend from '@suprsend/web-sdk';

      export const suprSendClient = new SuprSend(publicApiKey: string);
      ```
    </CodeGroup>

    | Params         | Description                                                                                                                    |
    | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
    | publicApiKey\* | This is public Key used to authenticate API calls to SuprSend. Get it in SuprSend dashboard **ApiKeys -> Public Keys** section |
  </Step>

  <Step title="Authenticate User">
    Authenticate user so that all the actions performed after authenticating will be w\.r.t that user. This is mandatory step and need to be called before using any other method. This is usually performed after successful login and on reload of page to re-authenticate user.

    <CodeGroup>
      ```typescript syntax theme={"system"}
      const authResponse = await suprSendClient.identify(
        distinctId: any,
        userToken?: string, // only needed in production environments for security
        { refreshUserToken: (oldUserToken: string, tokenPayload: Dictionary) => Promise<string> }
      );
      ```
    </CodeGroup>

    | Properties       | Description                                                                                                                                                                                                      |
    | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | distinctId\*     | Unique identifier to identify a user across platform.                                                                                                                                                            |
    | userToken        | Mandatory when enhanced security mode is on. This is ES256 JWT token generated in your server-side. Refer [docs](/docs/client-authentication#enhanced-security-mode-with-signed-user-token) to create userToken. |
    | refreshUserToken | This function is called by SDK internally to get new userToken before existing token is expired. The returned string is used as the new userToken.                                                               |

    **Returns:** `Promise<ApiResponse>`

    #### 2.1 Check if user is authenticated

    This method will check if user is authenticated i.e. `distinctId` is attached to SuprSend instance. To check for userToken also pass checkUserToken flag true.

    <CodeGroup>
      ```typescript syntax theme={"system"}
      suprSendClient.isIdentified(checkUserToken?: boolean): boolean
      ```
    </CodeGroup>
  </Step>

  <Step title="Reset user">
    This will remove user data from SuprSend instance. This is usually called on logout action.

    <CodeGroup>
      ```typescript syntax theme={"system"}
      await suprSendClient.reset();
      ```
    </CodeGroup>

    **Returns:** `Promise<ApiResponse>`
  </Step>
</Steps>

## Response structure

Almost all the methods in this SDK return response type `Promise<ApiResponse>`

<CodeGroup>
  ```typescript syntax theme={"system"}
  interface ApiResponse {
    status: 'success' | 'error';
    statusCode?: number;
    error?: { type?: string; message?: string };
    body?: any;
  }

  // success response
  {
    status: "success",
    body?: any,
    statusCode?: number
  }

  // error response
  {
    status: "error",
    error: {
      type: string,
      message: string
    }
  }
  ```
</CodeGroup>

***