# Getting Started

## Installing the web SDK

Run one of the following commands at the root of your javascript project to install the SDK.

Using npm:

```bash
npm install --save @payscore/web-widget-sdk
```

Using yarn:

```bash
yarn add @payscore/web-widget-sdk
```

Please make sure your package version is at least 1.1.0

## Selecting an Appropriate Environment

Payscore provides two environments for usage with the web-widget-sdk.

`staging` is used to develop and test your integration.

`production` is used for your application’s live environment.

Developers should be aware that API calls to create an applicant group and widget token will require you to use the same environment you are passing into the widget configuration.

## Obtaining an Access Token

To interact with the Payscore API, you must first generate an access token and attach the token to the Authentication header to authenticate requests. To accomplish this, follow the instructions found in the [Authentication Documentation](https://docs.payscore.com/api-reference/authentication).

## Creating a Applicant Group for the Applicant

Before you load the embedded widget, an applicant group needs to be created for the applicant. For instructions on creating an Applicant Group, please see our [Applicant Group Documentation](https://payscore.gitbook.io/payscore-unpublished/api-reference/applicant-groups). Make sure you set the `is_invitation_disabled` parameter to `true` to avoid sending an email or a text message invite to the applicant.

Once an applicant group is created, store the applicant IDs for each applicant within the group. That applicant id is how Payscore knows which applicant’s verifications to show in the embedded widget.

## Generate an Authenticated Widget Token for the Current Applicant

To generate a widget token, you make a `GET` request to the `/api/v1/applicants/{applicant_id}/widget_token` endpoint from your back-end with the following headers, and will receive the following response. We recommend adding a proxy endpoint in your backend that your front-end calls to obtain the widget token.

```typescript
// Path
https://app.staging.payscore.com/api/v1/applicants/{applicant_id}/widget_token

// Headers
Method: 'GET'
Accept: 'application/json'
Content-Type: 'application/json'
Authorization: 'Bearer {accessToken}'


// Response
{
    'widget_token': '1234'
}
```

## Incorporating the SDK

To use the widget, see the code example below. We recommend producing a new widget token every time you open the embedded widget.

{% tabs fullWidth="true" %}
{% tab title="Typescript" %}
{% code fullWidth="true" %}

```typescript
import {
    IncomeVerificationWidget,
    PayscoreEventType,
    PayscoreEvent
} from '@payscore/web-widget-sdk'

const onEvent = (event: PayscoreEvent, widget: IncomeVerificationWidget) => {
    const { type, timestamp } = event;

    switch(type) {
        case PayscoreEventType.IncomeVerificationLoaded:
            // Your code here
            break;
        case PayscoreEventType.IncomeVerificationStarted:
            // Your code here
            break;
        case PayscoreEventType.IncomeVerificationCompleted:
            widget.unmount();
            // Your code here
            break;
    }
};

const { widgetToken } = // Your code here

const incomeVerificationWidgetOptions = {
    widgetToken,
    applicantId,
    environment: 'staging' | 'production',
    options: {
        // Prevent user from closing the widget themselves
        hideCloseButton: true
    },
    onEvent
};

const incomeVerificationWidget = new IncomeVerificationWidget(payscoreWidgetOptions);

incomeVerificationWidget.load();
```

{% endcode %}
{% endtab %}

{% tab title="React" %}
{% code fullWidth="true" %}

```tsx
import {
    IncomeVerificationWidget,
    PayscoreEvent,
    PayscoreEventType
} from '@payscore/web-widget-sdk';
import { FunctionComponent, useCallback, useEffect, useRef } from 'react';

export interface IncomeVerificationWidgetProps {
    applicantId: string;
    environment: 'staging' | 'production';
    widgetToken: string;
}

export const IncomeVerificationWidgetComponent: FunctionComponent<IncomeVerificationWidgetProps> = ({
    applicantId,
    environment,
    widgetToken,
}) => {
    const widgetRef = useRef<IncomeVerificationWidget | null>(null);

    const onEvent = useCallback(
        (event: PayscoreEvent, widget: IncomeVerificationWidget) => {
            const { type, timestamp } = event;

            switch (type) {
                case PayscoreEventType.IncomeVerificationLoaded:
                    // Your code here
                    break;
                case PayscoreEventType.IncomeVerificationStarted:
                    // Your code here
                    break;
                case PayscoreEventType.IncomeVerificationCompleted:
                    widget.unmount();
                    // Your code here
                    break;
            }
        },
        []
    );

    useEffect(() => {
        if (!widgetToken || !applicantId) {
            return;
        }

        const incomeVerificationWidgetOptions = {
            environment,
            onEvent,
            screeningId: applicantId,
            widgetToken,
        };

        const incomeVerificationWidget = new IncomeVerificationWidget(incomeVerificationWidgetOptions);
        widgetRef.current = incomeVerificationWidget;

        incomeVerificationWidget.load();

        return () => {
            if (widgetRef.current) {
                widgetRef.current.unmount();
                widgetRef.current = null;
            }
        };
    }, [applicantId, environment, onEvent, widgetToken]);

    return null;
};

```

{% endcode %}
{% endtab %}
{% endtabs %}