Générer une courbe de couverture

Important : Cette fonctionnalité n'est disponible que pour les comptes figurant sur la liste d'autorisation. Si vous avez besoin d'y accéder, contactez votre représentant Google.

Une fois que vous avez rassemblé les paramètres de ciblage et un mix produits pour votre plan média, vous pouvez générer une courbe des budgets par rapport à la couverture potentielle à l'aide de la méthode GenerateReachForecast dans ReachPlanService. Pour en savoir plus sur les champs de la requête, consultez le glossaire et le guide du plan média.

Remarque : Dans le champ targeting.audience_targeting (AudienceTargeting), certaines valeurs user_interest_category de UserInterestInfo ne sont pas acceptées pour les prévisions de couverture. Utilisez ReachPlanService.ListPlannableUserInterests et ReachPlanService.ListPlannableUserLists pour interroger les critères compatibles avant d'appeler GenerateReachForecast.

Métriques de prévision

La réponse de GenerateReachForecast inclut diverses métriques dans le message Forecast, qui fournissent des insights sur les performances potentielles de votre campagne planifiée. En voici quelques-unes :

• Couverture (dans la cible et totale, y compris le covisionnage)
• Impressions (dans la cible et totales, y compris avec covisionnage, et visibles)
• Répartition de la fréquence effective (nombre d'utilisateurs uniques touchés au moins un certain nombre de fois, par exemple une, deux ou trois impressions ou plus)
• Actions des utilisateurs (vues TrueView, conversions et clics)

Prévoir la couverture pour Demand Gen

Lorsque vous générez des courbes pour les produits planifiables DEMAND_GEN, vous devez également inclure un taux de conversion attendu pour chaque produit.

Pour obtenir des suggestions de taux de conversion pour les produits planifiables compatibles, utilisez la méthode GenerateConversionRates. Cette méthode renvoie des suggestions de taux de conversion basées sur l'historique des performances de votre compte ou des taux suggérés basés sur les performances de tous les annonceurs.

Pour les produits DEMAND_GEN, GenerateConversionRates peut renvoyer plusieurs suggestions pour le même produit. Le champ surface_targeting est renseigné pour certaines suggestions, ce qui indique que la suggestion ne s'applique qu'à cette combinaison spécifique de surfaces (par exemple, YouTube Shorts). Si surface_targeting n'est pas renseigné, la suggestion correspond à la moyenne de la campagne Demand Gen pour ce produit. Lorsque vous générez des prévisions pour des campagnes Demand Gen avec ciblage par surface, utilisez la suggestion de taux de conversion la plus spécifique disponible.

En plus des taux de conversion, les utilisateurs de Demand Gen peuvent utiliser GenerateReachForecast pour projeter les clicks, ce qui est particulièrement utile pour les campagnes optimisées pour les clics, comme Demand Gen avec la stratégie d'enchères "Maximiser les clics".

Prévoir la couverture pour YouTube Select

YouTube Select (YTS) dans ReachPlanService est compatible avec le ciblage au niveau des lineups pour tous les emplacements YTS éligibles avec la tarification Réservation instantanée. Utilisez le champ youtube_select_lineup_targeting dans ReachPlanService.ListPlannableProducts pour identifier les lineups disponibles (youtube_select_lineup_targeting a remplacé le champ youtube_select_lineups, qui a été abandonné en v23 et supprimé en v24).

Avec la réservation instantanée, les erreurs suivantes peuvent se produire lors de la demande d'une prévision pour YTS :

• Inventaire disponible insuffisant
• Comptes sans dépenses désactivés

Enregistrer les courbes

Vous ne pouvez enregistrer que des courbes individuelles pour faciliter la tâche de vos utilisateurs. La mise en cache des courbes en masse est strictement interdite. Si vous devez générer des courbes en masse, contactez d'abord votre responsable de compte Google.

Gestion des exceptions

Les requêtes adressées à ReachPlanService doivent respecter la structure de base de l'API et peuvent renvoyer des erreurs courantes si la validation échoue.

En plus des erreurs courantes, ReachPlanService peut renvoyer des erreurs spécifiques à Reach Planner, listées dans ReachPlanError.

Exemple de code

La courbe inclut la couverture des impressions et des utilisateurs en chiffres absolus, ainsi que les tailles d'univers correspondant à la population recensée et à la taille de l'audience YouTube pour les données démographiques et le pays demandés.

Java

private void getReachCurve(
    ReachPlanServiceClient reachPlanServiceClient, GenerateReachForecastRequest request) {
  GenerateReachForecastResponse response = reachPlanServiceClient.generateReachForecast(request);
  System.out.println("Reach curve output:");
  System.out.println(
      "Currency, Cost Micros, On-Target Reach, On-Target Imprs, Total Reach, Total Imprs,"
          + " Products");
  for (ReachForecast point : response.getReachCurve().getReachForecastsList()) {
    System.out.printf(
        "%s, \"",
        Joiner.on(", ")
            .join(
                request.getCurrencyCode(),
                String.valueOf(point.getCostMicros()),
                String.valueOf(point.getForecast().getOnTargetReach()),
                String.valueOf(point.getForecast().getOnTargetImpressions()),
                String.valueOf(point.getForecast().getTotalReach()),
                String.valueOf(point.getForecast().getTotalImpressions())));
    for (PlannedProductReachForecast product : point.getPlannedProductReachForecastsList()) {
      System.out.printf("[Product: %s, ", product.getPlannableProductCode());
      System.out.printf("Budget Micros: %s]", product.getCostMicros());
    }
    System.out.printf("\"%n");
  }
}
ForecastReach.java
      

C#

public void GetReachCurve(ReachPlanServiceClient reachPlanService,
    GenerateReachForecastRequest request)
{
    GenerateReachForecastResponse response = reachPlanService.GenerateReachForecast(
        request);
    Console.WriteLine("Reach curve output:");
    Console.WriteLine(
        "Currency, Cost Micros, On-Target Reach, On-Target Impressions, Total Reach," +
        " Total Impressions, Products");
    foreach (ReachForecast point in response.ReachCurve.ReachForecasts)
    {
        Console.Write($"{request.CurrencyCode}, ");
        Console.Write($"{point.CostMicros}, ");
        Console.Write($"{point.Forecast.OnTargetReach}, ");
        Console.Write($"{point.Forecast.OnTargetImpressions}, ");
        Console.Write($"{point.Forecast.TotalReach}, ");
        Console.Write($"{point.Forecast.TotalImpressions}, ");
        Console.Write("\"[");
        foreach (PlannedProductReachForecast productReachForecast in
            point.PlannedProductReachForecasts)
        {
            Console.Write($"(Product: {productReachForecast.PlannableProductCode}, ");
            Console.Write($"Budget Micros: {productReachForecast.CostMicros}), ");
        }

        Console.WriteLine("]\"");
    }
}
ForecastReach.cs
      

PHP

private static function getReachCurve(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $productMix,
    string $locationId,
    string $currencyCode
) {
    // Valid durations are between 1 and 90 days.
    $duration = new CampaignDuration(['duration_in_days' => 28]);
    $targeting = new Targeting([
        'plannable_location_id' => $locationId,
        'age_range' => ReachPlanAgeRange::AGE_RANGE_18_65_UP,
        'genders' => [
            new GenderInfo(['type' => GenderType::FEMALE]),
            new GenderInfo(['type' => GenderType::MALE])
        ],
        'devices' => [
            new DeviceInfo(['type' => Device::DESKTOP]),
            new DeviceInfo(['type' => Device::MOBILE]),
            new DeviceInfo(['type' => Device::TABLET])
        ]
    ]);

    // See the docs for defaults and valid ranges:
    // https://developers.google.com/google-ads/api/reference/rpc/latest/GenerateReachForecastRequest
    $response = $googleAdsClient->getReachPlanServiceClient()->generateReachForecast(
        GenerateReachForecastRequest::build($customerId, $duration, $productMix)
            ->setCurrencyCode($currencyCode)
            ->setTargeting($targeting)
    );

    printf(
        "Reach curve output:%sCurrency, Cost Micros, On-Target Reach, On-Target Imprs," .
            " Total Reach, Total Imprs, Products%s",
        PHP_EOL,
        PHP_EOL
    );
    foreach ($response->getReachCurve()->getReachForecasts() as $point) {
        $products = '';
        /** @var ReachForecast $point */
        foreach ($point->getPlannedProductReachForecasts() as $plannedProductReachForecast) {
            /** @var PlannedProductReachForecast $plannedProductReachForecast */
            $products .= sprintf(
                '(Product: %s, Budget Micros: %s)',
                $plannedProductReachForecast->getPlannableProductCode(),
                $plannedProductReachForecast->getCostMicros()
            );
        }
        printf(
            "%s, %d, %d, %d, %d, %d, %s%s",
            $currencyCode,
            $point->getCostMicros(),
            $point->getForecast()->getOnTargetReach(),
            $point->getForecast()->getOnTargetImpressions(),
            $point->getForecast()->getTotalReach(),
            $point->getForecast()->getTotalImpressions(),
            $products,
            PHP_EOL
        );
    }
}
ForecastReach.php
      

Python

def request_reach_curve(
    client: GoogleAdsClient,
    customer_id: str,
    product_mix: list[PlannedProduct],
    location_id: str,
    currency_code: str,
):
    """Creates a sample request for a given product mix.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: The customer ID for the reach forecast.
        product_mix: The product mix for the reach forecast.
        location_id: The location ID to plan for.
        currency_code: Three-character ISO 4217 currency code.
    """
    # See the docs for defaults and valid ranges:
    # https://developers.google.com/google-ads/api/reference/rpc/latest/GenerateReachForecastRequest
    request: GenerateReachForecastRequest = client.get_type(
        "GenerateReachForecastRequest"
    )
    request.customer_id = customer_id
    # Valid durations are between 1 and 90 days.
    request.campaign_duration.duration_in_days = 28
    request.currency_code = currency_code
    request.cookie_frequency_cap = 0
    request.min_effective_frequency = 1
    request.planned_products = product_mix

    request.targeting.plannable_location_id = location_id
    request.targeting.age_range = (
        client.enums.ReachPlanAgeRangeEnum.AGE_RANGE_18_65_UP
    )

    # Add gender targeting to the request.
    gender_type: GenderTypeEnum
    for gender_type in [
        client.enums.GenderTypeEnum.FEMALE,
        client.enums.GenderTypeEnum.MALE,
    ]:
        gender: GenderInfo = client.get_type("GenderInfo")
        gender.type_ = gender_type
        request.targeting.genders.append(gender)

    # Add device targeting to the request.
    device_type: DeviceEnum
    for device_type in [
        client.enums.DeviceEnum.DESKTOP,
        client.enums.DeviceEnum.MOBILE,
        client.enums.DeviceEnum.TABLET,
    ]:
        device: DeviceInfo = client.get_type("DeviceInfo")
        device.type_ = device_type
        request.targeting.devices.append(device)

    reach_plan_service: ReachPlanServiceClient = client.get_service(
        "ReachPlanService"
    )
    response: GenerateReachForecastResponse = (
        reach_plan_service.generate_reach_forecast(request=request)
    )

    print(
        "Currency, Cost, On-Target Reach, On-Target Imprs, Total Reach,"
        " Total Imprs, Products"
    )
    point: ReachForecast
    for point in response.reach_curve.reach_forecasts:
        product_splits = []
        p: PlannedProductReachForecast
        for p in point.planned_product_reach_forecasts:
            product_splits.append(
                {p.plannable_product_code: p.cost_micros / ONE_MILLION}
            )
        print(
            [
                currency_code,
                point.cost_micros / ONE_MILLION,
                point.forecast.on_target_reach,
                point.forecast.on_target_impressions,
                point.forecast.total_reach,
                point.forecast.total_impressions,
                product_splits,
            ]
        )
forecast_reach.py
      

Ruby

def get_reach_curve(
  client,
  reach_plan_service,
  customer_id,
  product_mix,
  location_id,
  currency_code)
  duration = client.resource.campaign_duration do |d|
    # Valid durations are between 1 and 90 days.
    d.duration_in_days = 28
  end

  targeting = client.resource.targeting do |t|
    t.plannable_location_id = location_id
    t.age_range = :AGE_RANGE_18_65_UP
    t.genders << client.resource.gender_info do |gender|
      gender.type = :FEMALE
    end
    t.genders << client.resource.gender_info do |gender|
      gender.type = :MALE
    end
    t.devices << client.resource.device_info do |device|
      device.type = :DESKTOP
    end
    t.devices << client.resource.device_info do |device|
      device.type = :MOBILE
    end
    t.devices << client.resource.device_info do |device|
      device.type = :TABLET
    end
  end

  # See the docs for defaults and valid ranges:
  # https://developers.google.com/google-ads/api/reference/rpc/latest/GenerateReachForecastRequest
  response = reach_plan_service.generate_reach_forecast(
    customer_id: customer_id,
    campaign_duration: duration,
    planned_products: product_mix,
    currency_code: currency_code,
    targeting: targeting,
  )

  puts "Reach curve output:"
  puts "Currency, Cost Micros, On-Target Reach, On-Target Imprs, " \
    "Total Reach, Total Imprs, Products"

  response.reach_curve.reach_forecasts.each do |point|
    products = ""
    point.planned_product_reach_forecasts.each do |product|
      products += "(Product: #{product.plannable_product_code}, "\
        "Cost Micros: #{product.cost_micros})"
    end
    puts "#{currency_code}, #{point.cost_micros}, " \
      "#{point.forecast.on_target_reach}, " \
      "#{point.forecast.on_target_impressions}, " \
      "#{point.forecast.total_reach}, " \
      "#{point.forecast.total_impressions}, " \
      "#{products}"
  end
end
forecast_reach.rb
      

Perl

sub pull_reach_curve {
  my ($reach_plan_service, $reach_request) = @_;

  my $response = $reach_plan_service->generate_reach_forecast($reach_request);
  print "Reach curve output:\n";
  print "Currency,\tCost Micros,\tOn-Target Reach,\tOn-Target Imprs,\t" .
    "Total Reach,\tTotal Imprs,\tProducts\n";
  foreach my $point (@{$response->{reachCurve}{reachForecasts}}) {
    printf "%s,\t%d,\t%d,\t%d,\t%d,\t%d,\t'[", $reach_request->{currencyCode},
      $point->{costMicros}, $point->{forecast}{onTargetReach},
      $point->{forecast}{onTargetImpressions}, $point->{forecast}{totalReach},
      $point->{forecast}{totalImpressions};
    foreach my $productReachForecast (@{$point->{plannedProductReachForecasts}})
    {
      printf "(Product: %s, Budget Micros: %d), ",
        $productReachForecast->{plannableProductCode},
        $productReachForecast->{costMicros};
    }
    print "]'\n";
  }
}
forecast_reach.pl
      

curl

Remarque : Bien qu'aucun exemple de code REST direct ne soit fourni ici pour cette étape, vous pouvez effectuer cette opération à l'aide d'une requête REST manuelle.

Consultez la documentation sur l'interface REST de l'API Google Ads et les pages de référence spécifiques aux méthodes. Vous devrez créer la charge utile JSON en fonction des définitions proto.

Ressources clés :

• Utiliser REST
• Structure de l'interface REST
• Mappages de champs JSON
• Consultez la documentation de référence de l'API REST pour connaître le service et la méthode spécifiques.

Issue Tracker Google

Utilisez Google Issue Tracker pour poser des questions à l'assistance, signaler des bugs ou envoyer des demandes de fonctionnalités. Google suit, hiérarchise et publie des mises à jour sur vos demandes directement dans Issue Tracker. Pour en savoir plus, consultez Créer un problème dans l'outil Issue Tracker de Google.

Créez un problème à l'aide de l'un des modèles Issue Tracker suivants :

• Poser une question d'ordre général à l'assistance ou envoyer des commentaires sur la documentation
• Signaler un bug technique
• Envoyer une demande de fonctionnalité d'API

Remplissez tous les champs du modèle avec des informations détaillées afin que Google puisse reproduire et hiérarchiser votre demande. Google peut clôturer les rapports incomplets et vous demander d'envoyer un nouveau problème avec les informations manquantes.