We are sharing several Ads API updates that have been made effective over the past few weeks. These updates can help make it easier to manage Apps and App Events, add creative flexibility, and continue to improve parity with the Ads UI.
Specifically, we are releasing:
-
Account Apps: we have released a new endpoint,
account_apps, on the Ads API for versions 10+. This new endpoint will allow you to list all mobile apps associated with a Twitter Ads Account.
-
App Event Tags: the
app_event_tags endpoint has been updated to provide greater visibility into the status of App events. In particular, this update will allow you to pull the time of when we last received an event and what the status of existing events are.
-
Web Event Tags: a new
last_tracked_at field for the PUT and DELETE endpoints. We previously announced the last_tracked_at field for the GET endpoint.
-
Carousels Mixed Media Functionality: advertisers can now leverage Images and Videos within the same Carousel.
-
Batch Line Items API Fix: adding a number of fields for the
line_items endpoint that were missing from the batch line items endpoints.
-
Audience Estimate Operator Type: Introducing the
operator_type request parameter for the Audience Summary endpoint to better align with the Targeting Criteria endpoint and enable negated targeting.
Read more about these updates below.
account_apps endpoint: retrieve all mobile apps for an Ads account
This new endpoint will allow you to list and surface all mobile apps associated with a relevant advertiser account when running App Install or App Re-engagement objective campaigns.
That means that advertisers can avoid manually inputting an app_store_identifier during campaign or Card creation. Moving forward, you should begin to pull the list of app_store_identifiers that belong to relevant advertisers.
We heard your feedback around how the manual input process that was required when creating App campaigns can cause errors and issues. With that in mind, we are releasing this update to provide a simpler app ID selection process.
This release also helps bring the Ads API to better parity with the Ads UI - previously, the ability to view or retrieve a list of available mobile apps only existed in the Ads UI.
More information on this new endpoint can be found here.
App Event Tags: last_tracked_at and status fields
We are introducing two new fields: last_tracked_at and status. These new fields help provide greater visibility into the status of App events. In turn, this can help with App event troubleshooting and implementation.
The last_tracked_at field will be updated periodically with a timestamp to help users understand when events were last received for that event type. This value could be parsed and displayed to users, especially if there is a user interface for managing conversion events within your application.
The status field will provide information on existing event implementation. It can return three values:
-
TRACKING - Twitter has received data from your app within the past 24 hours.
-
DORMANT - Your app event has not sent any data from your app in the past 24 hours.
-
UNVERIFIED - Your app event hasn’t sent any data from your app yet. Your app event will be verified the first time a person takes the conversion action of that app event type in your app for which your SDK is activated.
More information on App Event Tags can be found here.
Web Event Tags: last_tracked_at
This is a new field for the web_event_tags PUT and DELETE endpoints. This field helps provide greater visibility with Web events. In turn this can help with Web Tag event troubleshooting and implementation.
The last_tracked_at field will be updated periodically with a timestamp to help users understand when events were last received for that event type. This value could be parsed and displayed to users, especially if there is a user interface for managing conversion events within your application.
For more information on GET /web_event_tags check out this page.
Carousels Mixed Media Functionality
We’ve built off of our existing Carousels format and introduced a new feature to allow advertisers to leverage both image and video assets within a single Carousel Ad, as opposed to having to choose one or the other. With this new feature addition, you’ll now have more flexibility to scale your creatives across Carousel Ads.
There will also be no changes to image or video specs with this new feature rollout. Mixed media will be supported across both Single-Destination and Multi-Destination Carousel Ads across the following objectives: Website Clicks, Reach, Engagements, and App.
Keep in mind, Video Views objective will not be supported for Carousels leveraging both types of assets. For Carousels using mixed media, please make sure aspect ratios remain consistent (1:1 image and 1:1 video, or 1.91:1 image and 16:9 video). We recommend leveraging this to maximize creative flexibility to highlight products or illustrate a story.
Carousels can be created using our POST accounts/:account_id/cards endpoint.
Batch Line Items API Fix
A number of fields for the line_items endpoint that were added over the past few releases were missing from the batch line items endpoints.
These have been added and the batch line_items endpoint should have parity with the non-batch line_items endpoint.
More information on the Line Items endpoint can be found here.
Audience Estimate operator_type
The Audience Estimate endpoint should work together with our existing Targeting Criteria endpoint. With that, this new operator_type field is being released to ensure input validation is better aligned with the Targeting Criteria endpoint, which already has this field.
This should allow you to pass the same valid JSON payload to both endpoints without having to modify them.
Additionally, the Audience Estimate endpoint will now allow negated targeting by setting operator_type=NE in the request. Note that the default value will be set to EQ.
Audience Estimate documentation can be found here. Target Criteria documentation can be found here.
Please let us know if you have any questions.
Twitter Ads API team