The aggregate targeting of most targeting types is a result of multiple
AssignedTargetingOption
resources. Within a targeting type,
each assigned targeting option may specify a different value, for example an
individual browser for TARGETING_TYPE_BROWSER
. If you want your
resource to target an additional browser, you can do so by
creating a new assigned targeting option of
TARGETING_TYPE_BROWSER
under that resource. Similarly, if you no
longer want to target a specific browser, you can delete the corresponding
assigned targeting option.
Audience group targeting doesn't follow this modular convention. Instead, all
audience IDs involved in a resource's targeting are assigned to that resource
through a single AssignedTargetingOption
of type
TARGETING_TYPE_AUDIENCE_GROUP
. Attempts to assign multiple audience
group assigned targeting options to a resource will return an error. This page
details the logic dictating this assigned targeting option and describes how to
correctly update existing audience group targeting.
Audience group targeting logic
The single audience group assigned targeting option has a set
AudienceGroupAssignedTargetingOptionsDetails
object
composed of lists of audience IDs, known as audience groups, to include and
exclude when serving ads. The aggregate targeting of the assigned targeting
option is a result of the following logical operations:
- Individual audience group objects of all types combine their included audiences by UNION.
- The
includedFirstAndThirdAudienceGroups
field, which consists of a list ofFirstAndThirdPartyAudienceGroup
objects, combines audience groups by INTERSECTION. - All audience group fields with the prefix "included", representing user lists or segments of user lists to positively target, are combined by UNION.
- All excluded audience group fields are combined by UNION and the COMPLEMENT of the result is combined with positive targeting by INTERSECTION.
In practicality, this means that the resulting
AudienceGroupAssignedTargetingOptionsDetails
will
target a user if both of the following conditions are met:
- The user falls into every audience group in the list of
includedFirstAndThirdPartyAudienceGroups
or falls into at least one ofincludedGoogleAudienceGroup
,includedCustomListGroup
, orincludedCombinedAudienceGroup
. - The user doesn't fall into
excludedFirstAndThirdPartyAudienceGroup
orexcludedGoogleAudienceGroup
.
Update audience group targeting
In order to update the audience group targeting of a line item, the current
assigned targeting option, if there is one, must be deleted and then a new
assigned targeting option with the desired changes needs to be created. This can
be done in a single request using
advertisers.lineItems.bulkEditAssignedTargetingOptions
.
Here's an example of how to update the existing the audience targeting of a line item by retrieving any existing audience group targeting and then making a bulk edit request:
Java
long advertiserId = advertiser-id; long lineItemId = line-item-id List<Long> addedGoogleAudienceIds = Arrays.asList(google-audience-id-to-add,...); // Build Google Audience targeting settings objects to add to audience // targeting. ArrayList<GoogleAudienceTargetingSetting> newGoogleAudienceSettings = new ArrayList<GoogleAudienceTargetingSetting>(); // Convert list of Google Audience IDs into list of settings. for (Long googleAudienceId : addedGoogleAudienceIds) { newGoogleAudienceSettings.add(new GoogleAudienceTargetingSetting() .setGoogleAudienceId(googleAudienceId)); } // Create relevant bulk edit request objects. BulkEditAssignedTargetingOptionsRequest requestContent = new BulkEditAssignedTargetingOptionsRequest(); requestContent.setLineItemIds(Arrays.asList(lineItemId)); AudienceGroupAssignedTargetingOptionDetails updatedAudienceGroupDetails; ArrayList<DeleteAssignedTargetingOptionsRequest> audienceGroupDeleteRequests = new ArrayList<DeleteAssignedTargetingOptionsRequest>(); try { // Retrieve existing audience group targeting. AssignedTargetingOption existingAudienceGroupTargetingOption = service .advertisers() .lineItems() .targetingTypes() .assignedTargetingOptions() .get( advertiserId, lineItemId, "TARGETING_TYPE_AUDIENCE_GROUP", "audienceGroup" ).execute(); // Extract existing audience group targeting details. updatedAudienceGroupDetails = existingAudienceGroupTargetingOption.getAudienceGroupDetails(); // Build and add delete request for existing audience group targeting. ArrayList<String> deleteAudienceGroupAssignedTargetingIds = new ArrayList<String>(); deleteAudienceGroupAssignedTargetingIds.add("audienceGroup"); audienceGroupDeleteRequests .add(new DeleteAssignedTargetingOptionsRequest() .setTargetingType("TARGETING_TYPE_AUDIENCE_GROUP") .setAssignedTargetingOptionIds( deleteAudienceGroupAssignedTargetingIds ) ); } catch (Exception e) { updatedAudienceGroupDetails = new AudienceGroupAssignedTargetingOptionDetails(); } // Set delete requests in edit request. requestContent.setDeleteRequests(audienceGroupDeleteRequests); // Construct new group of Google Audiences to include in targeting. GoogleAudienceGroup updatedIncludedGoogleAudienceGroup = updatedAudienceGroupDetails.getIncludedGoogleAudienceGroup(); if (updatedIncludedGoogleAudienceGroup != null) { List<GoogleAudienceTargetingSetting> updatedGoogleAudienceSettings = updatedIncludedGoogleAudienceGroup.getSettings(); updatedGoogleAudienceSettings.addAll(newGoogleAudienceSettings); updatedIncludedGoogleAudienceGroup .setSettings(updatedGoogleAudienceSettings); } else { updatedIncludedGoogleAudienceGroup = new GoogleAudienceGroup(); updatedIncludedGoogleAudienceGroup.setSettings(newGoogleAudienceSettings); } // Add new Google Audience group to audience group targeting details. updatedAudienceGroupDetails .setIncludedGoogleAudienceGroup(updatedIncludedGoogleAudienceGroup); // Create new targeting option to assign. AssignedTargetingOption newAudienceGroupTargeting = new AssignedTargetingOption(); newAudienceGroupTargeting .setAudienceGroupDetails(updatedAudienceGroupDetails); // Build audience group targeting create request and add to list of create // requests. ArrayList<AssignedTargetingOption> createAudienceGroupAssignedTargetingOptions = new ArrayList<AssignedTargetingOption>(); createAudienceGroupAssignedTargetingOptions.add(newAudienceGroupTargeting); ArrayList<CreateAssignedTargetingOptionsRequest> targetingCreateRequests = new ArrayList<CreateAssignedTargetingOptionsRequest>(); targetingCreateRequests.add(new CreateAssignedTargetingOptionsRequest() .setTargetingType("TARGETING_TYPE_AUDIENCE_GROUP") .setAssignedTargetingOptions( createAudienceGroupAssignedTargetingOptions ) ); // Set create requests in edit request. requestContent.setCreateRequests(targetingCreateRequests); // Configure and execute the bulk list request. BulkEditAssignedTargetingOptionsResponse response = service.advertisers().lineItems() .bulkEditAssignedTargetingOptions( advertiserId, requestContent).execute(); // Print the line item IDs that successfully updated. if (response.getUpdatedLineItemIds() != null && !response.getUpdatedLineItemIds().isEmpty()) { System.out.printf( "Targeting configurations for the following line item IDs were updated: %s.\n", Arrays.toString(response.getUpdatedLineItemIds().toArray())); } // Print the line item IDs the failed to update. if (response.getFailedLineItemIds() != null && !response.getFailedLineItemIds().isEmpty()) { System.out.printf( "Targeting configurations for the following line item IDs failed to update: %s.\n", Arrays.toString(response.getFailedLineItemIds().toArray())); // Print errors thrown for failed updates. System.out.println("The failed updates were caused by the following errors:"); for (Status error : response.getErrors()) { System.out.printf("Error Code: %s, Message: %s\n", error.getCode(), error.getMessage()); } }
Python
advertiser_id = advertiser-id line_item_id = line-item-id added_google_audiences = [google-audience-id-to-add,...] # Build Google Audience targeting settings objects to create. new_google_audience_targeting_settings = [] for google_audience_id in added_google_audiences: new_google_audience_targeting_settings.append( {'googleAudienceId': google_audience_id} ) try: # Retrieve any existing line item audience targeting. retrieved_audience_targeting = service.advertisers().lineItems( ).targetingTypes().assignedTargetingOptions().get( advertiserId=advertiser_id, lineItemId=line_item_id, targetingType="TARGETING_TYPE_AUDIENCE_GROUP", assignedTargetingOptionId="audienceGroup" ).execute() except Exception: print("Error retrieving existing audience targeting. Assuming no " "existing audience targeting.") retrieved_audience_targeting = {} updated_audience_group_details = {} # Copy over any existing audience targeting. if 'audienceGroupDetails' in retrieved_audience_targeting: updated_audience_group_details = retrieved_audience_targeting[ 'audienceGroupDetails'] # Append the new Google Audience IDs to any existing positive Google # audience targeting. if 'includedGoogleAudienceGroup' in updated_audience_group_details: updated_audience_group_details[ 'includedGoogleAudienceGroup']['settings'].extend( new_google_audience_targeting_settings) else: updated_audience_group_details['includedGoogleAudienceGroup'] = { 'settings': new_google_audience_targeting_settings } # Build bulk edit request. bulk_edit_request = { 'lineItemIds': [line_item_id], 'deleteRequests': [ { 'targetingType': "TARGETING_TYPE_AUDIENCE_GROUP", 'assignedTargetingOptionIds': [ "audienceGroup" ] } ], 'createRequests': [ { 'targetingType': "TARGETING_TYPE_AUDIENCE_GROUP", 'assignedTargetingOptions': [ {'audienceGroupDetails': updated_audience_group_details} ] } ] } # Update the audience targeting response = service.advertisers().lineItems( ).bulkEditAssignedTargetingOptions( advertiserId=advertiser_id, body=bulk_edit_request ).execute() # Print the line item IDs the successfully updated. if 'updatedLineItemIds' in response: print("Targeting configurations for the following line item IDs were updated: %s" % response['updatedLineItemIds']) # Print the line item IDs the failed to update. if 'failedLineItemIds' in response: print("Targeting configurations for the following line item IDs failed to update: %s" % response['failedLineItemIds']) if 'errors' in response: print("The failed updates were caused by the following errors:") for error in response["errors"]: print("Error code: %s, Message: %s" % (error["code"], error["message"]))
PHP
$advertiserId = advertiser-id; $lineItemId = line-item-id; $addedGoogleAudienceIds = array(google-audience-id-to-add,...); // Convert list of Google Audience IDs into list of Google Audience // settings. $newGoogleAudienceSettings = array(); foreach ($addedGoogleAudienceIds as $googleAudienceId) { $newSetting = new Google_Service_DisplayVideo_GoogleAudienceTargetingSetting(); $newSetting->setGoogleAudienceId($googleAudienceId); $newGoogleAudienceSettings[] = $newSetting; } // Create a bulk edit request. $requestBody = new Google_Service_DisplayVideo_BulkEditAssignedTargetingOptionsRequest(); $requestBody->setLineItemIds([$lineItemId]); $audienceGroupDeleteRequests = array(); try { // Retrieve existing audience group targeting. $existingAudienceGroupTargetingOption = $service ->advertisers_lineItems_targetingTypes_assignedTargetingOptions ->get( $advertiserId, $lineItemId, 'TARGETING_TYPE_AUDIENCE_GROUP', 'audienceGroup' ); // Extract existing audience group targeting details. $updatedAudienceGroupDetails = $existingAudienceGroupTargetingOption ->getAudienceGroupDetails(); // Build and add delete request for existing audience group // targeting. $deleteAudienceGroupAssignedTargetingIds = array(); $deleteAudienceGroupAssignedTargetingIds[] = "audienceGroup"; $audienceGroupDeleteRequest = new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest(); $audienceGroupDeleteRequest ->setTargetingType('TARGETING_TYPE_AUDIENCE_GROUP'); $audienceGroupDeleteRequest ->setAssignedTargetingOptionIds( $deleteAudienceGroupAssignedTargetingIds ); $audienceGroupDeleteRequests[] = $audienceGroupDeleteRequest; } catch (\Exception $e) { $updatedAudienceGroupDetails = new Google_Service_DisplayVideo_AudienceGroupAssignedTargetingOptionDetails(); } // Set delete requests in edit request. $requestBody->setDeleteRequests($audienceGroupDeleteRequests); // Construct new group of Google Audiences to include in targeting. $updatedIncludedGoogleAudienceGroup = $updatedAudienceGroupDetails ->getIncludedGoogleAudienceGroup(); if (!empty($updatedIncludedGoogleAudienceGroup)) { // Get existing settings. $updatedGoogleAudienceSettings = $updatedIncludedGoogleAudienceGroup->getSettings(); // Add new Google Audiences to existing list. $updatedGoogleAudienceSettings = array_merge( $updatedGoogleAudienceSettings, $newGoogleAudienceSettings ); // Set updated Google Audience list. $updatedIncludedGoogleAudienceGroup ->setSettings($updatedGoogleAudienceSettings); } else { // Create new Google Audience group. $updatedIncludedGoogleAudienceGroup = new Google_Service_DisplayVideo_GoogleAudienceGroup(); // Set list of new Google Audiences for targeting. $updatedIncludedGoogleAudienceGroup ->setSettings($newGoogleAudienceSettings); } // Add new Google Audience group to audience group targeting details. $updatedAudienceGroupDetails ->setIncludedGoogleAudienceGroup( $updatedIncludedGoogleAudienceGroup ); // Create new targeting option to assign. $newAudienceGroupTargeting = new Google_Service_DisplayVideo_AssignedTargetingOption(); $newAudienceGroupTargeting ->setAudienceGroupDetails($updatedAudienceGroupDetails); // Build audience group targeting create request and add to list of // create requests. $createAudienceGroupAssignedTargetingOptions = array(); $createAudienceGroupAssignedTargetingOptions[] = $newAudienceGroupTargeting; $createAudienceGroupTargetingRequest = new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest(); $createAudienceGroupTargetingRequest->setTargetingType( "TARGETING_TYPE_AUDIENCE_GROUP" ); $createAudienceGroupTargetingRequest->setAssignedTargetingOptions( $createAudienceGroupAssignedTargetingOptions ); $createRequests[] = $createAudienceGroupTargetingRequest; // Set create requests in edit request. $requestBody->setCreateRequests($createRequests); // Call the API, editing the assigned targeting options for the // identified line item. $response = $service ->advertisers_lineItems ->bulkEditAssignedTargetingOptions( $advertiserId, $requestBody ); // Print the line item IDs the successfully updated. if (!empty($response->getUpdatedLineItemIds())) { printf('Targeting configurations for the following line item IDs were updated:\n'); foreach ($response->getUpdatedLineItemIds() as $id) { printf('%s\n', $id); } } // Print the line item IDs the failed to update. if (!empty($response->getFailedLineItemIds())) { print('Targeting configurations for the following line item IDs failed to update:\n'); foreach ($response->getFailedLineItemIds() as $id) { printf('%s\n', $id); } print('The failed updates were caused by the following errors:\n'); foreach ($response->getErrors() as $error) { printf('Error Code: %s, Message: %s\n', $error->getCode(), $error->getMessage()); } }
Optimize audience targeting
Display & Video 360 offers the ability to expand beyond the reach of your selected audiences to new and relevant users through the optimized targeting feature.
Optimized targeting is set at the line item level and can be configured through
the targetingExpansion
field in the LineItem
resource.