How it works
You define an event source (a stream of conversions you send withlog_event) or an audience (a list of people you
sync with save_audience) once, for the advertiser. A seller account such as a
Meta ad account or a Snap ad account only understands its own objects: a Meta
dataset, a Snap Pixel, a TikTok pixel, a LinkedIn conversion rule, a Meta Custom
Audience. A mapping tells Apostra which of those objects is the same thing
as yours on that account.
There are two kinds of object on a seller account:
- Yours, once mapped. A pixel you map to one of your event sources works in every campaign that runs on that account. An audience you map is checked on the account and shows the seller’s size and match rate there. An audience already on an ad account mapped to an advertiser is that advertiser’s audience already, mapped for you (see Audiences already on your ad accounts). A campaign can target or exclude it on a seller that takes mapped audiences, and a seller that does not take them blocks the campaign’s launch. Campaign audiences lists which sellers take them.
- Seller-managed or unmapped. Objects that belong to one storefront, such as
a Meta Instant Forms leads source, or any object you leave unmapped, stay
specific to that storefront. They pass through unchanged and are usable in
that storefront’s own campaigns. You cannot map your event sources to
seller-managed objects: a save that names one is refused with
VALIDATION_ERRORon the entry’splatformId.
- Map. Save the mapping with
sellerAccountsonsave_event_sourceorsave_audience, or pick it on the Connections page. - Confirm. Apostra asks the seller account to confirm the object is there.
The mapping reads
pending, thensynced, typically within a minute. An audience also reports the seller’s own size and match rate. - Buy. When a media buy’s optimization goal names your event source, or its campaign targets or excludes your audience, Apostra sends the seller the mapped platform object instead of your id.
Action needed if you name your own event sources in conversion goals. Map
each event source on every seller account you buy on. A media buy whose goal
names an event source with no mapping on that account fails before anything
reaches the seller, unless the event source’s own id is the id of a pixel or
dataset on that account: then that pixel is used, as if you had mapped it.
Goals that carry a raw platform pixel id, buys with no event goal, and a Meta
product’s explicit
pixelId behave as before.Find what is on each account
Open the Connections page for one connected account. It lists the pixels, datasets and audiences already there, and whether each is yours (Mapped to) or only on that storefront. On Meta, the list holds every audience your connection can see on the ad account, including audiences you made in Meta such as lookalike and website audiences. Partner segments shared by a data provider are not listed and cannot be mapped. See Open Media Partners. Over MCP, callopen_connections_page with a connectionId and accountId:
get with the connection, its inventory and
one account:
upstreamObjectId. That is
the value you pass as platformId when you map. The account id (here 301) is
the accounts[].id from get({ "kind": "connection", "id": "992" }).
The inventory read returns live audience and event-source presences. Set
connectionInventoryObjectType to audience or event_source to inspect one
kind. Continue a longer result with connectionInventoryOffset; each page has
at most 50 rows. Terminal presences remain on the V2 compatibility read and
are deliberately excluded from V3 inventory.
Map an event source
Save the event source withsellerAccounts. Each entry names the seller account
and the id of the object on it:
platformId is the object you mapped, from the moment you save it. status is
pending until the seller account confirms it, then synced. If you change the
mapping on an account that already uses a confirmed object, platformId shows
the new one and the account reads pending, or names why the seller refused
it, while media buys already on that account keep using the confirmed one. Mapping an event source sends none of your conversion data to the
seller: Apostra only checks which pixel or dataset on the account the source
uses. So mapping needs no data-sharing setting, and the Conversion events
switch on the Connections page does not affect it.
Event types must match
A destination that declares the event types it accepts must accept every type your source records. A LinkedIn conversion rule records one type, so it maps only to a source whoseeventTypes are all on that rule’s list. A source with no
eventTypes records every type, so it maps only to a destination that declares
none. Meta, Snap and TikTok datasets and pixels accept all types. A mismatch is
refused at save time with VALIDATION_ERROR on the entry’s platformId. Narrow
the source’s eventTypes, or map a destination that accepts them.
Use the source in a campaign goal
Name the event source in an event goal. Use your ownevent_source_id, not the
platform’s id:
event_source_id. Seller-managed sources and a platform’s built-in events
are sent unchanged.
When a buy is refused
A media buy whose goal names an event source that cannot be used on that account fails before anything reaches the seller. A read of the media buy showserrorCode: "invalid_request", owned by you (buyer_input), and the failure
reason starts with one of the codes below. Fix the cause, then create a new media
buy.
A mapping that is still being confirmed is not a refusal: the buy is held and
sent once the mapping reads
synced. If a Meta product on the buy sets an
explicit pixelId that differs from the dataset you mapped, the buy is refused
for the conflict. Remove the explicit pixelId or map the same dataset.
The full list of blocker codes and what each media-buy state does is in
Measurement and incrementality.
Audiences already on your ad accounts
An audience that already exists on a seller account needs no upload and no mapping. Every live audience on an ad platform account you connected directly, such as a Meta ad account, that is mapped to an advertiser becomes one of that advertiser’s audiences on its own, already mapped to that account. That includes a Meta Custom Audience, website audience or lookalike made in Ads Manager. An account reached through a sales agent is not synced this way; map an audience there as described in Map an audience. Apostra gives it its ownaudienceId, such as
aud_4fX9kQ2mT7bR1vLz8NcYp, the first time it sees it. The platform’s own
audience id, such as 23850000000012345, is the platformId of its
sellerAccounts[] entry for that account, and it carries the platform’s name.
One platform audience is one audience: a Meta audience shared into two of the
advertiser’s ad accounts is one audience mapped to both. It appears in
get({ "kind": "audience", "advertiserId": "42" }) once Apostra’s hourly read
of the account lists it.
Its sellerAccounts[] entry for the account reads synced once the platform
reports the audience ready. Target or exclude it by its audienceId; Apostra
sends the platform its own id. A platform audience id in audience_include or
audience_exclude is not an audienceId, so a buy that names one is refused.
When the audience is deleted on the platform, or the account no
longer lists it, it stays in the list but reads SELLER_AUDIENCE_MISSING on
that account, and a buy that names it is refused. Nothing is uploaded for these
audiences. Their members and name are managed on the platform, so
save_audience refuses with VALIDATION_ERROR to add or remove their members,
rename them or delete them.
Map an audience
Map one of your own audiences the same way. The audience must already exist: save its members first, then map it once it appears in the advertiser’s audience list:get({ "kind": "audience", "advertiserId": "42" }). An audience read
takes the advertiser, not an audience id, and returns every audience for it, 50
per page (audienceOffset pages on).
get({ "kind": "audience", "advertiserId": "42" }), and find the audience by
audienceId; each of its sellerAccounts[] entries carries status, platformId, and, once confirmed, the seller’s own size
and match in match:
match is null until the mapping is confirmed or when the seller reports
nothing. If the audience is not on the account, or the seller reports it
deleted, suspended or failed, the mapping reads SELLER_AUDIENCE_MISSING.
Check the id on the Connections page and map the right audience.
If the platform lists the audience but cannot deliver ads to it yet, because it
is still being built or is too small, the mapping stays pending with
SELLER_OBJECT_SYNC_PENDING. It is checked again about every hour and confirms
once the platform can deliver to it, so you don’t need to map it again.
A media buy that needs an audience the account can’t use is refused before
anything reaches the seller. Its failure reason starts with the blocker code and
names the audience by name and audience id. For an audience the platform lists
but can’t deliver to yet, the code is SELLER_OBJECT_SYNC_PENDING with
correctable recovery, and the reason says what the platform reported. If the
platform is still processing the audience, wait for it to finish. If the
platform reports the audience below its minimum size for targeting, waiting
will not help, and the reason says so. Add members to an audience you sync with
save_audience. For an audience synced in from the ad account, rebuild or
refresh it on the platform. Meta, for example, reports an inactive lookalike as
too small. Or remove the audience from the media buy. Create the media buy again
once the mapping reads synced. SELLER_OBJECT_SYNC_FAILED is kept for a check
that failed outright.
On a seller that takes campaign audiences, a media buy whose
audience_include or audience_exclude names an id that is not one of the
advertiser’s audiences is refused the same way, with
SELLER_AUDIENCE_MISSING, and its reason names each such id. Use an
audienceId that get({ "kind": "audience", "advertiserId": "42" }) lists, or
create the audience with save_audience.
Unmap
To end a mapping, send the account withunmap: true instead of a platformId.
This works the same on save_event_source and save_audience:
INVALID_STATE and names the media buys;
unmap once they have ended or been canceled. A later media buy on that account
that names the source fails as if it were never mapped.
Troubleshooting
Related
- Log events: send conversions to a registered event source.
- Measurement and incrementality: how a source reaches each seller account and every refusal code.
- Open Media Partners: the Connections page and its account inventory.
- V3 tool reference:
save_event_source,save_audience, and the connection inventory read.