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:

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

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:

window.syntage.onboarding.init({ sat: true });

Example of initialization with buroDeCredito only:

window.syntage.onboarding.init({ buroDeCredito: true });

To include both parameters:

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.

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

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:

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:

{
    "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) 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:

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

Using with TypeScript

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 to include this script in your application. When using only React, you can use the react-helmet library to manage scripts. You can also create a custom hook to inject the script into your application:

Use https://onboarding.sandbox.syntage.com/script.min.js when testing onboarding in sandbox.

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,
});

Start here

API concepts

Integration guides

Embedding Entity Onboarding

Include the onboarding script

Start onboarding

Test environment

Event subscriptions

Error descriptions

Content Security Policies

Tips

Using with TypeScript

Using with React

​Include the onboarding script

​Start onboarding

​Test environment

​Event subscriptions

​Error descriptions

​Content Security Policies

​Tips

​Using with TypeScript

​Using with React

Include the onboarding script

Start onboarding

Test environment

Event subscriptions

Error descriptions

Content Security Policies

Tips

Using with TypeScript

Using with React