Actions and login

An action is a button on an item that sends a request to your site, or opens one of your pages. You declare actions in the manifest. How the button looks is set in the view.

"actions": {
  "like": { "method": "POST", "url": "/api/items/{id}/like", "auth": "session", "toggle": true },
  "cart": { "mode": "deeplink", "url": "/cart/add/{id}" }
},
"auth": {
  "login": "/login",
  "csrf": { "meta": "csrf-token", "header": "X-CSRF-TOKEN" }
}

Fields of an action

Field	Meaning
`method`	The HTTP method.
`url`	The URL, with `{id}` for the item id.
`auth`	`none`, `session` (cookies, same origin) or `bearer` (a token from `auth.device_link`).
`toggle`	`true` says the same call switches the state on and off.
`mode`	`"deeplink"`: the program only opens the URL (http or https only).
`response`	`"empty"` for an action that answers with no body.

What a session action sends

A program calls an action with the visitor’s cookies only when auth is session, and only on the origin of the manifest. The call carries Accept: application/json and X-Requested-With: XMLHttpRequest. A redirect is not followed and counts as an error.

A 401, 403 or 419 answer means the visitor is not signed in.
A success is a 2xx answer whose body is a JSON object: { "ok": true, "state": { ... } }. "ok": false is a failure.
With "response": "empty", a 2xx answer with an empty body is the success.
The state in the answer updates item.state, the button and the mark on the card.

CSRF

If the manifest declares auth.csrf, every non-GET session action carries the token in csrf.header.

"auth": { "csrf": { "meta": "csrf-token", "header": "X-CSRF-TOKEN", "cookie": "XSRF-TOKEN" } }

The wall reads the token from a <meta name="<csrf.meta>"> tag or from the cookie csrf.cookie of the document it runs in, and only when that document is on the manifest’s origin. If it cannot find the token, the call is not sent and counts as not signed in. A site that uses cookie sessions should declare auth.csrf, or accept these actions only with its own origin check.

Signing in

When an action answers “not signed in”, the wall shows the signin_on_site text. If the manifest has auth.login, the button then opens that page, with a second press.

A headset has no keyboard, so a site can offer a phone sign-in. auth.device_link is the endpoint of that flow: the wall shows a code and a QR code, the visitor approves on their phone, and the wall polls. A code is used once and lives at most ten minutes. On Level 3 you give the wall an account adapter for it. See Wall API.

Deep links

An action with "mode": "deeplink" opens a page of your site, for example an add-to-cart URL. It always asks for a second press. The checkout stays on your site.