Embedding Entity Onboarding

This guide explains how to integrate the onboarding experience directly into your application. This allows users to enter their credentials and authorization without needing to access an external page.

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

Using the Script

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

Note that the values must be boolean.

Test Environment

To use the script in a test environment, add the following script to your application. It will include the sandbox script and display a warning indicating 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 syntage.onboarding provides a subscribe method to receive notifications of events from the Entity Onboarding.

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

window.syntage.onboarding.subscribe("syntage.onboarding.success", () => {
    console.info('syntage.onboarding.success');
});

The step parameter will return 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 are used to 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, you have to include the rules 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:

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.sandbox.syntage.com/script.min.js",
  slug: "YOUR_COMPANY_SLUG",
  sandbox: true,
});