Setup guide

You need an account with credits, a website address you control, and access to your app's HTML. Setup takes a few minutes.

Install

Copy your site key from the dashboard and add this tag to every page where the guide should appear, using your key:

<script src="https://cdn.arrowly.dev/guide.js" data-key="pk_your_site_key" data-api="https://api.arrowly.dev" defer></script>

Keep data-api: without it, the guide sends its requests to the address it was loaded from, which is not the API. The site key is public, so it is safe in your HTML. Your allowed websites and limits protect it.

Allowed websites

In the dashboard, add each origin where the tag runs: scheme, host and any port, with no path or trailing slash, such as https://app.example.com. The match is exact, so www and staging addresses each need their own entry.

Keep areas private

Add data-guide-ignore to any element. The guide leaves it and everything inside it out of what it reads, and it won't point there.

<section data-guide-ignore>
  <h2>Patient record</h2>
</section>

Options

data-key is required. Without it the script logs a console warning and does nothing. data-api sets the API address. These two are optional:

data-color="#c2185b" sets the color of the arrow, sign and panel.
data-launcher="false" removes the floating "Help me" button, so you can start guides from your own code.

Start guides from your code

window.BigArrow.start("Create a property"); // starts a guide for this goal
window.BigArrow.cancel();                    // stops the current guide
window.BigArrow.open();                      // opens the panel

Each call has to run after the script has loaded.

Data handling

Snapshots, the guide's text reading of a page, never carry input values, password content or query strings, or anything under [data-guide-ignore].
The API logs metadata only, such as tenant, guide id, step kind, tokens, cost and latency, with request status and error codes. It never logs snapshots or goals.
The model provider, Anthropic, receives page structure and labels and the user's goal, together with the company's product name and description, its help docs, the steps of the guide so far and the browser's language.
Page structure means the page address without its query string, the title, visible headings, the open dialog's label, status messages, and each control's role, state, visible name, placeholder, options and context.
Context is the text that tells a control apart from similar ones: its section heading, field group, dialog, or the first cell of its table row.
The steps of the guide so far include each sign and question shown, the user's choices and free-text answers, which controls they used, and the page addresses, without query strings.
A user's goal and free-text answers are sent as they were typed, so they hold whatever the user chooses to write.
Labels, headings, status messages and context can contain personal data shown on the page, such as a customer's name on a button or in a table row. Marking those areas with data-guide-ignore keeps them out.

The Privacy Policy and DPA have the full terms.

Content Security Policy

If your site sends a Content Security Policy, add these sources to it:

script-src https://cdn.arrowly.dev; connect-src https://api.arrowly.dev

You do not need a style-src entry or 'unsafe-inline'. The guide also needs no unsafe-eval, images or fonts. Sites that use nonces or hashes in style-src keep working. We test this exact policy against the real guide.js on a page where everything else is denied.

If your script-src uses 'strict-dynamic', browsers ignore the address above. Put your nonce on the tag instead, and keep the connect-src entry.

The guide loads its styles in a way that a policy doesn't block, a method available across browsers since March 2023. An older browser falls back to a style element, which a strict policy blocks, so the arrow won't display properly there unless inline styles are allowed.

Testing

Try the public demo first to see what a guide looks like.
Add your staging site to your allowed websites and put the tag on it.
Open a page. The "Help me" button should appear.
Ask for a task your help docs cover, and follow it to the end.
Reload the page in the middle of a guide. It should continue.
Check that the guide ignores your data-guide-ignore areas.
Check the guide and your credit use in the dashboard.

Testing uses real credits: a guide costs one credit at its first answer, even if that answer has no arrow.

Troubleshooting

If no button appears, look for a warning about data-key in the browser console. For other problems, open the Network tab and find the requests to /v1/step.

A CORS error and no status is the most common install mistake. The browser checks with an OPTIONS request first, and if no allowed website matches the page's origin, it stops there: the real request is never sent, so there is no error code to read. Your users see a connection error. Check your allowed websites first, then your site key.

If the request has a status, use the list below. The response body names the error, but the browser can hide the body of a 401 or 403 behind a CORS error, so go by the status. For out_of_credits and daily_limit, your users see only a general message.

`invalid_site_key (401)`

The key in data-key doesn't exist. Copy it again from the dashboard, and check that data-api points at the API.

`origin_not_allowed (403)`

The page's origin isn't in the allowed websites for this key. Add it exactly, with its scheme and any port. You see this status only when another Arrowly customer allows the same origin. Usually the browser blocks the request first, as described above.

`out_of_credits (402)`

Your balance is zero, so new guides stop. A guide already charged finishes. Buy credits in the dashboard.

`daily_limit (429)`

You reached your daily guide limit. Raise it in the dashboard, or wait until the next day.

`rate_limited (429)`

Too many steps in a minute. Wait a minute and try again.

`service_unavailable (503)`

We couldn't confirm your site key or credits, and no free guide runs in that case. Try again in a moment.