API Integration documentation

What the script publishes

The global variables set on window, and exactly what they contain.

The script sets four global variables, and nothing else. None of them is required to submit a form: they are meant for pages that want to display the business's contact details or build their own interface.

window.WEBSITE

The website identifier, plus only the fields the client has ticked in the Public data section of the website's page.

window.WEBSITE = {
    id: '019f0000-0000-7000-8000-00000000000a',
    // Only if the field is ticked by the client:
    name: 'Portails & Fermetures',
    url: 'https://portails-fermetures.fr',
    email: '[email protected]',
    phone: '03 89 00 00 00',
    company: 'Portails & Fermetures SARL',
    address: '12 rue des Remparts',
    zipcode: '68000',
    city: 'Colmar',
    country: 'France',
    logo: 'https://…/logos/12/logo.png',
    departments: [{ code: '68', name: 'Haut-Rhin' }]
};

Do not assume any field is present: by default, window.WEBSITE only contains id. A website that displays its phone number must read it with a guard (WEBSITE.phone || ''), and the client must tick the field in their panel.

window.FORMS

The forms loaded in the page, filled as they arrive: empty when the script starts, then completed after each request — the first one, and those made for forms added to the page later. A form is added once per language. It does not list every form of the website: the script only knows their identifiers until it finds them in the page — see How forms are loaded.

Each time forms are added, the script dispatches rikochey:forms-loaded on document, with the new forms in event.detail.forms:

document.addEventListener('rikochey:forms-loaded', function (event) {
    event.detail.forms.forEach(function (form) {
        console.log(form.slug, form.locale);
    });
});

A form has this shape — the same as returned by Load the forms of a page:

window.FORMS = [{
    slug: 'contact',
    locale: 'en',
    submit_button_text: 'Send',
    css_selector: null,
    injection_position: 'inside',
    html_wrapper: null,
    appearance: { '--rk-form-accent': '#1f6f5c', '--rk-form-radius': '6px' },
    fields: [{
        name: 'email',
        label: 'Email',
        type: 'email',
        is_required: true,
        show_label: true,
        is_multiple: false,
        placeholder: '[email protected]',
        help_text: null,
        link_url: null,
        options: [],
        attributes: { maxlength: '255' },
        visibility: null
    }, {
        name: 'privacy',
        label: 'I accept the [privacy policy].',
        type: 'consent',
        is_required: true,
        show_label: true,
        is_multiple: false,
        placeholder: null,
        help_text: null,
        link_url: 'https://www.example.com/privacy',
        options: [],
        attributes: {},
        visibility: null
    }],
    privacy_notice: null
}];

visibility is only set for a conditionally displayed field; it then holds match (all or any) and the list of conditions.

privacy_notice is the notice shown under the submit button — see Privacy notice below.

Languages

locale is the language the form is rendered in, picked by the server — see Languages. submit_button_text and every text of fields are already translated into it; a text the client has not translated falls back on the source language, one by one. submit_button_text is null when the client left it empty: the script then uses its own button text, in that language. The confirmation message is never published: it comes with the server's response.

The same form shown in two languages on one page appears twice, once per locale.

Field texts

  • placeholder: the text to show in the empty field, already computed — the one set by the client, otherwise, when the label is hidden, the label itself, followed by * for a required field; null when neither applies. Always null for checkboxes, radio buttons, hidden and consent fields.
  • help_text: a hint shown under the field, plain text. The script renders it in a <small class="rikochey-help"> referenced by the field's aria-describedby.
  • link_url: for a consent field only, the address of the policy.

A consent field is a single checkbox, sent as "1" when checked. Its label is the text shown next to it, where the part in square brackets is the link to link_url; without brackets, the whole label is the link; without link_url, there is no link and the brackets are dropped. The label never contains HTML. The script renders:

<label class="rikochey-consent">
    <input type="checkbox" name="privacy" value="1" required>
    I accept the <a href="https://www.example.com/privacy" target="_blank" rel="noopener noreferrer">privacy policy</a>. *
</label>

In attached mode, write the same checkbox in your form with the field's name. A required consent that is not checked is refused with a 422; once accepted, the request keeps the text as displayed, the link and the language as proof.

Privacy notice

A form without a consent field informs visitors with a short notice under the submit button. privacy_notice is null when the notice is not shown — hidden by the client, or replaced by a consent field of the form, even a conditional one. Otherwise:

privacy_notice: {
    text: null,                                  // null: the script's default text
    url: 'https://www.example.com/privacy'       // http(s) only, or null
}

text and url are in the rendered language, with the same fallback on the source as the other texts; a translated address that is not http or https falls back on the source one. With text set to null, the script uses its default text in the rendered language — in English: By submitting this form, you agree that your data will be used to process your request. The link follows the consent rule: the part in square brackets becomes the link to url; without brackets, a Privacy policy link is added after the text; without url, there is no link and the brackets are dropped. In automatic rendering, the script renders:

<small class="rikochey-privacy">
    By submitting this form, you agree that your data will be used to process your request.
    <a href="https://www.example.com/privacy" target="_blank" rel="noopener noreferrer">Privacy policy</a>
</small>

In attached mode, the script adds nothing: write the notice yourself under your submit button — see Automatic rendering or attached mode.

window.RECAPTCHA_SITE_KEY

The applicable reCAPTCHA site key, or null if the website's captcha chain contains no reCAPTCHA. The script uses it on its own: you do not need to.

window.VISITOR_HASH

The visitor's technical fingerprint, set after the tracking call. It is used to attribute a request to the visit that produced it. It is not an identity: it is recomputed server-side on every submission, and your value is only a hint.