Exemples de script pour la gestion des groupes d’annonces
Les sections suivantes présentent des exemples de scripts qui effectuent différentes actions sur des groupes d’annonces.
Ajouter des groupes d’annonces
Pour ajouter un groupe d’annonces, commencez par obtenir la campagne à laquelle ajouter le groupe d’annonces. Utilisez l’objet CampaignSelector pour sélectionner la campagne. L’utilisation de la withIds méthode offre de meilleures performances que le passage du nom de la campagne dans la withCondition méthode.
Ensuite, appelez la méthode newAdGroupBuilder de la campagne pour obtenir un générateur que vous utilisez pour spécifier les propriétés du groupe d’annonces. La seule propriété requise est le nom du groupe d’annonces (voir la withName méthode ), qui doit être unique dans la campagne. Si vous ne spécifiez pas de valeur CPC, elle est définie par défaut sur le montant minimal de l’enchère pour la devise de votre compte. Vous devez uniquement spécifier la langue si la campagne ne le spécifie pas ; sinon, elle hérite de la valeur de langue de la campagne. Par défaut, la status du groupe d’annonces est suspendue.
L’appel de la méthode du build générateur crée le groupe d’annonces de façon asynchrone ; Les scripts ajoutent le groupe d’annonces à un moment donné avant la fin du script ou si vous appelez l’une des méthodes de l’opération de génération. Pour plus d’informations sur ce processus, consultez Qu’est-ce qu’un générateur ?
function main() {
// The ID of the campaign to add the ad groups to.
// IDs in Scripts are string integers.
var campaignId = 'CAMPAIGN ID GOES HERE';
var campaign = getCampaign(campaignId);
// Ad groups to add.
var adGroups = [];
adGroups.push({
name : 'AD GROUP NAME GOES HERE',
cpc : 2.25,
language : 'English' // Required if the campaign doesn't specify a language
});
adGroups.push({
name : 'AD GROUP NAME GOES HERE',
cpc : 1.25,
language : 'English' // Required if the campaign doesn't specify a language
});
var operations = [];
if (campaign != null)
{
for (var adGroup of adGroups) {
var operation = addAdGroup(
campaign,
adGroup.name,
adGroup.cpc,
adGroup.language);
operations.push(operation);
}
}
else {
Logger.log("Unable to retrieve campaign, " + campaignId);
}
checkBuildStatus(operations, adGroups);
}
// Get the campaign using its ID.
function getCampaign(id) {
var iterator = AdsApp.campaigns()
.withIds([id])
.get();
// Return the campaign if it exists; otherwise, null.
if (iterator.hasNext()) {
return iterator.next();
}
else {
return null;
}
}
// Add the ad group to the specified campaign.
// Returns the builder's operation object, which you use to
// check the status of the add operation.
function addAdGroup(campaign, name, cpc, language) {
return campaign.newAdGroupBuilder()
.withName(name)
.withCpc(cpc)
.withLanguage(language)
.build();
}
// Check the ad group's build status.
function checkBuildStatus(operations, adGroups) {
for (var i = 0; i < operations.length; i++) {
if (!operations[i].isSuccessful()) {
for (var error of operations[i].getErrors()) {
Logger.log(`Failed to add, ${adGroups[i].name}. Error: ${error}`);
}
}
}
}
Obtenir tous les groupes d’annonces
Pour obtenir tous les groupes d’annonces dans un compte, appelez d’abord la méthode de adGroups l’objet AdsApp pour obtenir le sélecteur. Ensuite, appelez la méthode du get sélecteur pour obtenir un itérateur que vous utilisez pour itérer dans la liste des groupes d’annonces. Étant donné que l’exemple ne spécifie aucun filtre, le sélecteur retourne tous les groupes d’annonces dans le compte. Pour déterminer le nombre de groupes d’annonces dans l’itérateur, appelez la méthode de l’itérateur totalNumEntities .
function main() {
// Gets all ad groups in the account.
var iterator = AdsApp.adGroups().get();
// Iterates through the list of ad groups and logs
// each ad group's name.
while (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obtenir un groupe d’annonces par nom
Pour obtenir un groupe d’annonces par son nom, appelez d’abord la méthode de l’objet adGroupsAdsApp pour obtenir le sélecteur. Le sélecteur contient un certain nombre de méthodes de filtre que vous utilisez pour filtrer la liste des groupes d’annonces. Utilisez la withCondition méthode pour filtrer les groupes d’annonces pour un nom de groupe d’annonces spécifique. Notez que les opérandes et les opérateurs respectent la casse.
Ensuite, appelez la méthode du get sélecteur pour obtenir l’itérateur. Les noms de groupes d’annonces au sein d’une campagne sont uniques, mais il est possible pour plusieurs campagnes d’avoir des groupes d’annonces portant le même nom. Pour cette raison, si vous filtrez uniquement par nom, l’itérateur peut contenir plusieurs groupes d’annonces.
Si vous souhaitez obtenir un groupe d’annonces par nom à partir d’une campagne spécifique, incluez une withCondition méthode qui spécifie le nom de la campagne (CampaignName = '<campaignnamegoeshere>').
function main() {
// The name of the ad group to get.
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad groups with the specified name.
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.get();
// Need a loop because multiple campaigns can have
// an ad group with the same name.
while (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obtenir un groupe d’annonces par ID
Si vous avez accès à l’ID du groupe d’annonces, utilisez-le à la place. L’utilisation d’ID pour obtenir des entités offre de meilleures performances. Au lieu d’utiliser la withCondition méthode filter, utilisez la withIds méthode . Par exemple : withIds(['12345']).
function main() {
var adGroupId = '12345';
var iterator = AdsApp.adGroups()
.withIds([adGroupId])
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obtenir un groupe d’annonces par nom à partir d’une campagne spécifique
function main() {
var adGroupName = 'AD GROUP NAME GOES HERE';
var campaignName = "CAMPAIGN NAME GOES HERE";
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
}
}
Obtenir les données de performances d’un groupe d’annonces
Pour obtenir les métriques de performances d’un groupe d’annonces, appelez la méthode getStats du groupe d’annonces. Lorsque vous obtenez le groupe d’annonces, vous devez spécifier la plage de dates des données de métriques souhaitées. Vous pouvez spécifier la plage de dates à l’aide d’un littéral prédéfini, tel que LAST_MONTH ou AUJOURD’HUI, ou d’une date de début et de fin. Pour spécifier la plage de dates, utilisez l’une des forDateRange méthodes lorsque vous sélectionnez le groupe d’annonces (voir AdGroupSelector).
Pour obtenir la liste des métriques accessibles, consultez l’objet Stats .
function main() {
var campaignName = 'CAMPAIGN NAME GOES HERE';
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad group. You need to specify the date range of the
// performance data you want to get.
var iterator = AdsApp.adGroups()
.forDateRange('LAST_WEEK')
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
// If the ad group is found, log some metrics.
if (iterator.hasNext()) {
var adGroup = iterator.next();
var metrics = adGroup.getStats(); // Gets the performance metrics.
}
}
Suspendre un groupe d’annonces
Lorsque vous ajoutez un groupe d’annonces, son status est suspendu par défaut. Pour activer le groupe d’annonces, appelez la méthode du groupe d’annonces enable . Pour modifier la status du groupe d’annonces en Paused, appelez la méthode du groupe d’annoncespause. Pour déterminer la status du groupe d’annonces, appelez les méthodes , isPausedet isRemoved du isEnabledgroupe d’annonces.
function main() {
var campaignName = 'CAMPAIGN NAME GOES HERE';
var adGroupName = 'AD GROUP NAME GOES HERE';
// Get the ad group.
var iterator = AdsApp.adGroups()
.withCondition(`Name = '${adGroupName}'`)
.withCondition(`CampaignName = '${campaignName}'`)
.get();
if (iterator.hasNext()) {
var adGroup = iterator.next();
adGroup.pause();
}
}