Embeddables

We allow different components from Recrubo.app UI to be embedded in your application using iframes. This allows you to provide your users with advanced features like our Inbox, BotStudio or embedding the WhatsApp sign up process in your ATS.

Embedding Recrubo Components

Embedding Recrubo components in your application involves two main steps: Authentication and Initialization.

Authentication

To grant a user access to the features within Recrubo iframes, an authentication token is required. Ensure that your application's user has a corresponding user record within Recrubo system (see Recrubo's User API for more details).

You can retrieve an authentication token for the user by sending a request to Recrubo's authentication endpoint POST public/v2/embed/authenticate.

Example

curl "https://api.recrubo.app/public/v2/embed/authenticate" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <organization_api_key>" \
    -d '{ 
        "userId": "<recrubo_user_record_id>",
        "originUrl": "<origin_of_iframe_request>"
    }'

OriginUrl

To ensure the token cannot be used to embed through different sources than intended this is stored and validated when initializing the iframe component. This url requires the protocol, subdomain, root domain and top level domain. Some examples being https://recrubo.app or https://demo.recrubo.app. The url should correspond to the origin of embedding, being the client side application which will use the <iframe> tag to embed a component

Note: The request for the authentication token should be performed from a server-side application to safeguard your API_KEY.

Initialization

Now that you have acquired an authentication token, you can initialize any Recrubo iframe component. Initialization is carried out using the postMessage API, which allows your application to communicate the token and settings to Recrubo's app.

<iframe id="inboxFrame" src="https://api.recrubo.app/public/v2/embed/component/inbox"></iframe>

<!-- A script to communicate the user token as soon as the iframe is loaded -->
<script type="text/javascript">
    const inbox = document.querySelector('#inboxFrame')

    inbox.onload = (evt) => {
        const inboxSettings = {
            action: 'initialize',
            token: localStorage.getItem('userToken')
        }

        // second argument is the origin of the target window, in this case the production url of the Recrubo webapp
        inbox.contentWindow.postMessage(inboxSettings, 'https://recrubo.app')
    }
</script>

postMessage

postMessage is used to send the token from your application to Recrubo, which stores the token in a http-only cookie for their domain.

The data in the message posted will always be an object, containing the action key and optionally additional data. All Recrubo iframes accept the initialize action it takes care of authentication using the token and configuration of the component.

Each iframe component might also have additional actions that are used to further configure or control the component. These are optional and depend on the specific component.

Reference the Embedding the Inbox guide for more details on embedding an actual component.

For more details on using the postMessage API, check out the postMessage documentation on MDN Web Docs.

Receiving events

Apart from sending instructions to the embedded component, the component also sends notifications. Mainly status updates like initialized or user actions that cannot be resolved within the component itself.

As an example, we will use the Inbox candidateOpenExternal, this event is triggered when the user wants to open the candidate details in an external tab. Our component has no knowledge of your system's structure so in order to open the candidate details within your system we send an event instead.

// add an event listener to the window hosting the Inbox Iframe
window.addEventListener('message', (message) => {
    // validate the origin of the event
    if (message.origin !== 'https://recrubo.app') {
        throw new Error('Unknown event origin')
    }

    // after the user token is verified and the component loaded successfully
    if (message.data.component === 'recrubo' && message.data.event === 'initialized') {
        console.log('Recrubo iframe initialized successfully')
    }

    // received when the user wants to open a candidate in a different tab
    if (message.data.component === 'inbox' && message.data.event === 'candidateOpenExternal') {
        window.open(`https://yourdomain.com/candidate/${message.data.externalId}`, '_blank').focus()
    }
})

This code will:

• log a message once the component is fully initialized

• open the candidate in a different tab (once the user triggers that action) using the externalId.

All events have the following keys in their data:

• component

• event

component is set to 'recrubo' in case the event is not component bound, ie initialized or authenticationError

Available Embeddables

Inbox

BotStudio

GenerateFlow