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

# Embedding Entity Onboarding

This guide explains how to integrate the onboarding experience directly into your application. Use it when you want users to complete onboarding on your own site instead of redirecting them to a Syntage-hosted page.

## Include the onboarding script

To get started, add the following script to your application:

```html theme={null}
<script
  id="syntage-onboarding-id"
  type="text/javascript"
  src="https://onboarding.syntage.com/script.min.js"
  data-key="YOUR_COMPANY_SLUG"
  async
></script>
```

Get your slug from the [Entity Onboarding configuration page](https://app.syntage.com/en/settings/entity-onboarding).

## Start onboarding

Once the script is added, you can access the available methods via `window.syntage.onboarding`. To start the onboarding process, use the `init()` method. Specify which data you want to request from users.

Example of initialization with `sat` only:

```js theme={null}
window.syntage.onboarding.init({ sat: true });
```

Example of initialization with `buroDeCredito` only:

```js theme={null}
window.syntage.onboarding.init({ buroDeCredito: true });
```

To include both parameters:

```js theme={null}
window.syntage.onboarding.init({ sat: true, buroDeCredito: true });
```

The option values must be boolean.

## Test environment

To use onboarding in sandbox, add the sandbox script to your application. The sandbox script displays a warning that onboarding is in test mode.

```html theme={null}
<script
  id="syntage-onboarding-id"
  type="text/javascript"
  src="https://onboarding.sandbox.syntage.com/script.min.js"
  data-key="YOUR_COMPANY_SLUG"
  async
></script>
```

## Event subscriptions

The `window.syntage.onboarding` object provides a `subscribe` method to receive onboarding events.

To subscribe to the success event, use the following code:

```js theme={null}
window.syntage.onboarding.subscribe("syntage.onboarding.success", (_, step) => {
  console.info("syntage.onboarding.success", step);
});
```

The `step` parameter returns `sat` or `buroDeCredito`.

To subscribe to error events, use the following code:

```js theme={null}
window.syntage.onboarding.subscribe("syntage.onboarding.error", (_, error) => {
  console.info("syntage.onboarding.error", error);
});
```

The returned error object contains a `code` and a message. Example of an error:

```json theme={null}
{
    "code": "ERROR_CODE",
    "step": "sat"
}
```

### Error descriptions

* Credential disabled: `credentialDisabled`
* Credential invalid: `credentialInvalid`
* Generic error: `error`
* Unknown error: `unknownError`

## Content Security Policies

[Content Security Policies (CSP)](https://content-security-policy.com/) are delivered as a header to your user's browser by your web server. They declare which dynamic resources are allowed to load on your page.

If there is a Content Security Policy issue, you will see something similar to the below error:

```
 Refused to load the script 'https://onboarding.syntage.com/script.min.js' because it violates the following Content Security Policy directive: "script-src 'self' 'unsafe-eval' 'unsafe-inline'" ...
```

If needed, include Syntage in your CSP configuration:

```
default-src ... https://*.syntage.com
frame-src ... https://*.syntage.com
```

## Tips

If the script is not yet loaded when executing `init()`, you can listen for the `entityOnboardingLoaded` event to ensure proper initialization:

```js theme={null}
try {
  window.syntage.onboarding.init({ ... });
} catch {
  window.addEventListener("entityOnboardingLoaded", (e) => {
    window.syntage.onboarding.init({ ... });
  });
}
```

### Using with TypeScript

```ts theme={null}
type SyntageOnboarding = {
  onboarding: {
    init(options: { sat: boolean; buroDeCredito: boolean }): void;
    destroy(): void;
    subscribe<T extends 'syntage.onboarding.success' | 'syntage.onboarding.error'>(
      event: T,
      callback: T extends 'syntage.onboarding.success'
        ? (event: T, step: 'sat' | 'buroDeCredito') => void
        : (
            event: T,
            error: {
              code: 'credentialDisabled' | 'credentialInvalid' | 'error' | 'unknownError';
              step: 'sat' | 'buroDeCredito';
            },
          ) => void,
    ): void;
  };
};

interface Window {
  syntage: SyntageOnboarding;
}
```

### Using with React

In Next.js, you can use the [script tag](https://nextjs.org/docs/pages/api-reference/components/script) to include this script in your application. When using only React, you can use the [react-helmet](https://www.npmjs.com/package/react-helmet) library to manage scripts.

You can also create a custom hook to inject the script into your application:

<Note>
  Use `https://onboarding.sandbox.syntage.com/script.min.js` when testing onboarding in sandbox.
</Note>

```js theme={null}
const useImportWidgetScript = ({ scriptUrl, slug, sandbox }) => {
  const scriptRef = useRef(null);

  useEffect(() => {
    if (!slug || typeof slug !== 'string') {
      console.error('Invalid slug provided.');
      return;
    }

    const script = document.createElement('script');
    script.async = true;
    script.src = scriptUrl;
    script.setAttribute('data-key', slug);

    if (sandbox) {
      script.setAttribute('data-sandbox', sandbox);
    }

    scriptRef.current = script;
    document.body.appendChild(script);

    return () => {
      if (scriptRef.current) {
        document.body.removeChild(scriptRef.current);
        scriptRef.current = null;
      }
    };
  }, [scriptUrl, slug, sandbox]);
};

// Usage
useImportWidgetScript({
  scriptUrl: "https://onboarding.syntage.com/script.min.js",
  slug: "YOUR_COMPANY_SLUG",
  sandbox: false,
});
```