Register a placement

What the CMS does once, when a banner placement is created: it sends its own address, the player the placement belongs to, where a click should go, and credentials to read that CMS with. Back comes a permanent identifier and the embed code to paste into a page.

CMS base URL

Player UUID The external player in the CMS. One player is one banner placement.

Link URL Where a click goes when the booking on screen has no click URL of its own in the CMS, in a new tab. Blank sends nothing: a new placement gets the address shown, an existing one keeps the link it has.

CMS username

CMS password

Sealed with AES-GCM before it reaches the registry. Leave both blank and fill the token field instead if this CMS uses a bearer token.

CMS bearer token (instead of username and password)

Refresh seconds

Provisioning secret Sent straight from this browser to /provision as the Authorization header. It is never stored, never rendered into this page, and the server showing you this form does not have it.

Tag size Only affects the embed code and the preview below — a placement is not bound to a size.

Doing this from your CMS instead

The form above is only a convenience. The integration is one HTTP call, made once, when a banner placement is created.

POST /provision
Authorization: Bearer <provisioning secret>
Content-Type: application/json

{
  "cms_base_url": "https://demo.doohlabs.com/index.php/api/v3",
  "player_id": "c295ecf4-8e6a-4ddc-8012-947bcee913ef",
  "cms_user": "<username>",
  "cms_pass": "<password>",
  "refresh": { "mode": "interval", "floor_sec": 30 },
  "link_url": "https://www.doohlabs.com/forms/contact-us"
}

Field	Meaning
`cms_base_url`	Your CMS API root. A trailing slash makes no difference — it is the same CMS either way.
`player_id`	The external player this placement belongs to.
`cms_user` + `cms_pass`	Credentials to read that CMS with. Sealed with AES-GCM before storage.
`cms_token`	A bearer token instead of the pair above. Send one or the other.
`refresh`	Optional. `{ "mode": "interval", "floor_sec": 30 }` or `{ "mode": "off" }`. Default 30 s. Re-provisioning with a different value updates it.
`link_url`	Optional. Absolute http(s) URL a click opens, in a new tab, whenever the booking on screen has no `click_url` of its own in the CMS. Omitted: a new placement gets Doohlabs’ contact page, an existing one keeps its link. Sent: updates it.

200 OK

{
  "placement_id": "af30630d-8358-4d5f-9f40-b256041a4947",
  "embed_url": "https://adserver.example.com/af30630d-8358-4d5f-9f40-b256041a4947",
  "created": true,
  "refresh": { "mode": "interval", "floor_sec": 30 },
  "link_url": "https://www.doohlabs.com/forms/contact-us"
}

Response	Meaning
`placement_id`	Permanent. Build the embed code from it and never recompute it.
`embed_url`	What the iframe points at.
`created`	`false` when the placement already existed. Calling again is safe: the same CMS and player always return the same id, and a rotated password updates the credential in place without moving it.
`refresh`	The policy now in effect for this placement, after applying whatever this call sent.
`link_url`	Where a click goes now, after applying whatever this call sent.

Status	When
`200`	Registered, or already registered — see `created`.
`400`	Malformed JSON, a `cms_base_url` or `link_url` that is not an absolute URL, or no credentials.
`401`	The provisioning secret did not match. Nothing is registered.
`503`	The registry is not configured or cannot be reached. Retry later.