Skip to main content
A seller account connects its ad server as an inventory source through V3. The supported ad servers are Google Ad Manager, FreeWheel, SpringServe, AdsWizz, Broadsign and Epsilon Retail Media (CitrusAd). What Broadsign asks for and does is described below. The Google Ad Manager role and permissions Apostra needs, and what each one is for, are described in Google Ad Manager access. What FreeWheel, SpringServe and AdsWizz ask for is described in Ad server access.

Start from an agent

An agent starts a connection with save_inventory_source and only adServer:
type is google_ad_manager, freewheel, springserve, adswizz, broadsign or citrusad. The call creates nothing. It returns action: "ad_server_form" and opens the Connect ad server form, where the seller enters the ad server’s details and credentials. Credentials are never passed in an agent’s tool call, so they never pass through chat. Sending adServer with any other field is refused with VALIDATION_FAILED. For Google Ad Manager the result also carries serviceAccountEmail. Apostra signs in to GAM with a service account it creates for your organization, and you add that email as a user in your GAM network before connecting. The first call creates the service account; later calls return the same one. An agent can tell the seller which email to add without opening the form. open_page({ "page": "connect_ad_server" }) opens the same form without choosing an ad server first.

Choose an inventory source

Call get({ "kind": "source_options" }) in a seller account to read the available ad servers and partner sales agents. object.options gives each option’s label, summary, connection action, certification and known limits. A partner agent appears when its owner can serve other sellers and has published its connection contract. Selecting a partner opens its connection form, which asks for the details the partner requires.

What the form does

The form sends the ad server’s configuration and credentials to Apostra, which forwards the credentials to the managed source and never stores them on the Apostra connection or returns them. On an existing source, the ad-server source page sends the replacement configuration the same way. Google Ad Manager’s network settings are replaced in place. For the other ad servers the credentials are rotated in place, so the source keeps its products and sync history. A credential save always sends the secret that signs in to the ad server. Any other secret already on file that the save leaves out is kept, so you do not have to enter it again. Settings that go with a kept secret, such as the Broadsign Control domain id, are kept too when the save does not send them. To remove a secret on purpose, name it in removeSecrets. The secret that signs in to the ad server cannot be removed; deactivate the source instead. A source you deactivated, or that Apostra deactivated after a sync error, is disabled: it no longer syncs and buyers cannot book it. To bring it back, connect the same ad-server account again. For Google Ad Manager, connect the same network code. The disabled source is switched back on in place, so it keeps its products, pricing and approvals. It does not create a second source. A disabled source cannot be switched back on directly when Apostra holds no record of the managed principal it acts as; connecting the account again supplies it. When the managed source refuses a credential save, nothing on the source changes and the form shows why:
  • A save it cannot accept, for example one that changes the sign-in email without sending the password again, or that names a secret the ad server does not have, is refused with a message saying what to send.
  • If the secrets on file can no longer be read, the save is refused and asks you to enter every secret for the connection again.
  • If another save changed the connection’s secrets while this one was being checked, the save is refused with a conflict. Send it again.
Epsilon Retail Media connects in two steps: the form creates the source, then stores its API key. If storing the key fails, the form retries against the source it already created instead of creating a second one. These form writes are page-only. They are not part of an agent’s tool list, the public V3 HTTP API or the SDKs.

Broadsign

Broadsign sells digital out-of-home screen time. Apostra connects to Broadsign Guaranteed Campaigns (Broadsign Direct), the system that books screen time. What you provide.
  • A production Broadsign Guaranteed Campaigns login email and password. The user must be active and allowed to read screens and to create and book proposals.
  • The three-letter currency your Broadsign domain prices in.
Broadsign does not report a currency through its API, so the currency you enter is the currency every booking uses. It must match your storefront’s settlement currency before a booking can become ready. What Apostra keeps. Every Broadsign connection pins the broadsign:v1 connection contract, which fixes the production Direct API and an email and password login. The password is forwarded to the managed source and never stored on or returned by the Apostra connection. Only the email, the production environment, the domain currency and the contract stay on the connection. What the connection does.
  • Reads your domain’s screens.
  • Books one Broadsign proposal per media buy, with one line item per package.
  • Reads each buy’s status and its flight-to-date delivery: delivered impressions from the line items, and spend as those impressions at the booked CPM.
  • Sends flight date changes to Broadsign as amendments.
  • Cancels.
  • With Broadsign Control access: sends creative to your screens, pauses and resumes a buy, and reads daily plays and impressions from proof-of-play.
Budget and impression changes are refused. Without Control access, assigning a creative to a buy is refused, pausing and resuming are refused, delivery stays at flight-to-date totals, and you schedule creative in Broadsign yourself.
Apostra has not yet run this connection, with or without Control access, against a live Broadsign account. It was built from Broadsign’s published API descriptions, so expect adjustments when the first one connects.
If Broadsign rejects the login, the connection reports ADAPTER_INVALID_CREDENTIALS or ADAPTER_PERMISSION_DENIED. Check the email and password and the user’s permissions, then save them again on the ad-server source page.

Optional Broadsign Control access

Broadsign Control is the separate Broadsign API for creative content and proof-of-play. Adding it is optional; you can connect Broadsign Guaranteed Campaigns without it. With it, Apostra can do three more things:
  • Send creative to your screens. Apostra checks the asset, uploads it to Control from its URL, adds it to the booked campaign’s schedule, and reads the schedule back to confirm it is there. The asset must be a hosted image or video at a public https URL, with no third-party trackers. Once Apostra has your screens, its width and height must equal the resolution of every screen in the package. Duration is not checked, and companion banners, placement routing and weights are not supported. If Broadsign has not created the Control campaign yet, the creative stays uploaded and Apostra attaches it once the campaign exists.
  • Pause and resume a buy. Apostra sets the campaign inactive or active in Control and reports success only when Control shows it. Broadsign Direct has no pause, so without Control a pause is refused.
  • Report what actually played. Apostra reads daily plays and impressions from Control’s proof-of-play, and shows spend as those impressions at the booked CPM. A report can cover any day in the 90 days before the last read. Apostra’s own delivery totals cover impressions, spend, clicks and completed views, and do not store play counts yet.
When you add Control access, the connection test also checks it, and a Control failure fails the whole test. Apostra signs in to Control with the token only. Broadsign recommends client certificates in production, which Apostra does not support. To add it, enter two values together, or neither:
  • Control API token: a Broadsign Control REST API token. It is write-only: forwarded to the managed source and encrypted there, never stored on the Apostra connection or returned.
  • Control domain id: the numeric id of the Broadsign Control domain that holds your screens. It is stored and returned as controlDomainId on V3 reads of the connection (include: ["adServerConnection"]), so you can see Control is set up.
Control access uses the broadsign:v2 connection contract. A save that sends the Control values with broadsign:v1, or sends the token without the domain id, is refused. A save that sends only the domain id keeps the token already on file, and is refused when there is none. To get a token, ask Broadsign Services to enable REST API access for an API user on your Control domain. A Control administrator then generates the token in Broadsign Control Administrator, under the user’s properties, in Credentials. Treat it like a password. To replace it, save a new token and the domain id on the ad-server source page. The token is never shown again, and you do not need to enter it again: leave the token field blank when you change your other Broadsign credentials, and the token on file is kept. Through the API, a save that leaves the token out keeps it, along with the stored domain id when the save does not send one. To remove Control, clear both Control fields on the ad-server source page, which says that saving removes Control access. Through the API, name it in removeSecrets: ["control_api_token"], so Control is never removed by accident.

After connecting

The new source appears in search({ "kind": "inventory_source" }). Read its connection state and setup progress with get({ "kind": "inventory_source", "id": "SOURCE_ID" }). See Reading an inventory source for what that read returns. To see which of a managed source’s secrets are on file, add include: ["adServerConnection"]. Alongside the connection, the read returns contract, the connection contract the source is pinned to, and secrets, each declared secret as { "key", "label", "onFile" }. It never returns a secret’s value.