Exemples de script pour la gestion des groupes d’annonces

Les sections suivantes présentent des exemples de scripts qui effectuent diverses 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 cette withIds méthode offre de meilleures performances que la transmission du nom de la campagne dans la withCondition méthode.

Appelez ensuite 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 de CPC, le montant d’enchère minimal correspond par défaut à la devise de votre compte. Vous devez uniquement spécifier la langue si la campagne ne la spécifie pas ; sinon, il hérite de la valeur de langue de la campagne. Par défaut, le status du groupe d’annonces est suspendu.

L’appel de la méthode du constructeur crée le groupe d’annonces build de manière asynchrone ; Scripts ajoute 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, voir Qu’est-ce qu’un constructeur ?

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 d’un compte, appelez d’abord la méthode de l’objet adGroupsAdsApp pour obtenir le sélecteur. Appelez ensuite 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 renvoie tous les groupes d’annonces du 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 nom, appelez d’abord la méthode de l’objet adGroupsAdsApp pour obtenir le sélecteur. Le sélecteur contient plusieurs méthodes de filtrage 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 sont sensibles à la casse.

Ensuite, appelez la méthode du sélecteur pour obtenir l’itérateurget. Les noms de groupes d’annonces au sein d’une campagne sont uniques, mais il est possible que plusieurs campagnes aient 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. Utilisez la withIds méthode au lieu d’utiliser la méthode de withCondition filtrage. 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 AUJOURDHUI, ou de dates de début et de fin. Pour spécifier la plage de dates, utilisez l’une forDateRange des méthodes lorsque vous sélectionnez le groupe d’annonces (voir AdGroupSelector).

Pour obtenir la liste des mesures auxquelles vous pouvez accéder, consultez l’objet Statistiques .

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 définir le status du groupe d’annonces sur Suspendu, appelez la méthode du groupe d’annoncespause. Pour déterminer le status d’un groupe d’annonces, appelez les méthodes , isPausedet isRemoved du groupe d’annoncesisEnabled.

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();
    }
}