Start from an agent
An agent starts a connection withsave_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
Callget({ "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 inremoveSecrets. 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.
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: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.
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.
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.
- 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
controlDomainIdon V3 reads of the connection (include: ["adServerConnection"]), so you can see Control is set up.
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 insearch({ "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.