Gérer les listes de clients

Consultez ce guide pour en savoir plus sur la mise à jour, la suppression et la création de rapports sur les listes de clients.

Mettre à jour une liste avec OfflineUserDataJobService

Une fois que vous avez créé vos listes de clients et configuré le ciblage, il est préférable de les actualiser régulièrement.

Pour mettre à jour vos listes avec les dernières données, il est généralement plus efficace d'ajouter ou de supprimer des utilisateurs individuels plutôt que de supprimer tous les utilisateurs de la liste et de les importer à partir de zéro.

Ajouter des utilisateurs à une liste

Pour ajouter des utilisateurs à une liste existante, créez un OfflineUserDataJob de la même manière que vous le feriez pour créer une liste de clients.

Java

private void addUsersToCustomerMatchUserList(
    GoogleAdsClient googleAdsClient,
    long customerId,
    boolean runJob,
    String userListResourceName,
    Long offlineUserDataJobId,
    ConsentStatus adPersonalizationConsent,
    ConsentStatus adUserDataConsent)
    throws UnsupportedEncodingException {
  try (OfflineUserDataJobServiceClient offlineUserDataJobServiceClient =
      googleAdsClient.getLatestVersion().createOfflineUserDataJobServiceClient()) {
    String offlineUserDataJobResourceName;
    if (offlineUserDataJobId == null) {
      // Creates a new offline user data job.
      OfflineUserDataJob.Builder offlineUserDataJobBuilder =
          OfflineUserDataJob.newBuilder()
              .setType(OfflineUserDataJobType.CUSTOMER_MATCH_USER_LIST)
              .setCustomerMatchUserListMetadata(
                  CustomerMatchUserListMetadata.newBuilder().setUserList(userListResourceName));
      // Adds consent information to the job if specified.
      if (adPersonalizationConsent != null || adUserDataConsent != null) {
        Consent.Builder consentBuilder = Consent.newBuilder();
        if (adPersonalizationConsent != null) {
          consentBuilder.setAdPersonalization(adPersonalizationConsent);
        }
        if (adUserDataConsent != null) {
          consentBuilder.setAdUserData(adUserDataConsent);
        }
        // Specifies whether user consent was obtained for the data you are uploading. See
        // https://www.google.com/about/company/user-consent-policy for details.
        offlineUserDataJobBuilder
            .getCustomerMatchUserListMetadataBuilder()
            .setConsent(consentBuilder);
      }

      // Issues a request to create the offline user data job.
      CreateOfflineUserDataJobResponse createOfflineUserDataJobResponse =
          offlineUserDataJobServiceClient.createOfflineUserDataJob(
              Long.toString(customerId), offlineUserDataJobBuilder.build());
      offlineUserDataJobResourceName = createOfflineUserDataJobResponse.getResourceName();
      System.out.printf(
          "Created an offline user data job with resource name: %s.%n",
          offlineUserDataJobResourceName);
    } else {
      // Reuses the specified offline user data job.
      offlineUserDataJobResourceName =
          ResourceNames.offlineUserDataJob(customerId, offlineUserDataJobId);
    }

    // Issues a request to add the operations to the offline user data job. This example
    // only adds a few operations, so it only sends one AddOfflineUserDataJobOperations request.
    // If your application is adding a large number of operations, split the operations into
    // batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job. See
    // https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    // and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    // for more information on the per-request limits.
    List<OfflineUserDataJobOperation> userDataJobOperations = buildOfflineUserDataJobOperations();
    AddOfflineUserDataJobOperationsResponse response =
        offlineUserDataJobServiceClient.addOfflineUserDataJobOperations(
            AddOfflineUserDataJobOperationsRequest.newBuilder()
                .setResourceName(offlineUserDataJobResourceName)
                .setEnablePartialFailure(true)
                .addAllOperations(userDataJobOperations)
                .build());

    // Prints the status message if any partial failure error is returned.
    // NOTE: The details of each partial failure error are not printed here, you can refer to
    // the example HandlePartialFailure.java to learn more.
    if (response.hasPartialFailureError()) {
      GoogleAdsFailure googleAdsFailure =
          ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
      System.out.printf(
          "Encountered %d partial failure errors while adding %d operations to the offline user "
              + "data job: '%s'. Only the successfully added operations will be executed when "
              + "the job runs.%n",
          googleAdsFailure.getErrorsCount(),
          userDataJobOperations.size(),
          response.getPartialFailureError().getMessage());
    } else {
      System.out.printf(
          "Successfully added %d operations to the offline user data job.%n",
          userDataJobOperations.size());
    }

    if (!runJob) {
      System.out.printf(
          "Not running offline user data job '%s', as requested.%n",
          offlineUserDataJobResourceName);
      return;
    }

    // Issues an asynchronous request to run the offline user data job for executing
    // all added operations.
    offlineUserDataJobServiceClient.runOfflineUserDataJobAsync(offlineUserDataJobResourceName);

    // BEWARE! The above call returns an OperationFuture. The execution of that future depends on
    // the thread pool which is owned by offlineUserDataJobServiceClient. If you use this future,
    // you *must* keep the service client in scope too.
    // See https://developers.google.com/google-ads/api/docs/client-libs/java/lro for more detail.

    // Offline user data jobs may take 6 hours or more to complete, so instead of waiting for the
    // job to complete, retrieves and displays the job status once. If the job is completed
    // successfully, prints information about the user list. Otherwise, prints the query to use
    // to check the job again later.
    checkJobStatus(googleAdsClient, customerId, offlineUserDataJobResourceName);
  }
}

C#

private static string AddUsersToCustomerMatchUserList(GoogleAdsClient client,
    long customerId, string userListResourceName, bool runJob,
    long? offlineUserDataJobId, ConsentStatus? adPersonalizationConsent,
    ConsentStatus? adUserDataConsent)
{
    // Get the OfflineUserDataJobService.
    OfflineUserDataJobServiceClient service = client.GetService(
        Services.V24.OfflineUserDataJobService);

    string offlineUserDataJobResourceName;
    if (offlineUserDataJobId == null)
    {
        // Creates a new offline user data job.
        OfflineUserDataJob offlineUserDataJob = new OfflineUserDataJob()
        {
            Type = OfflineUserDataJobType.CustomerMatchUserList,
            CustomerMatchUserListMetadata = new CustomerMatchUserListMetadata()
            {
                UserList = userListResourceName,
            }
        };

        if (adUserDataConsent != null || adPersonalizationConsent != null)
        {
            // Specifies whether user consent was obtained for the data you are uploading.
            // See https://www.google.com/about/company/user-consent-policy
            // for details.
            offlineUserDataJob.CustomerMatchUserListMetadata.Consent = new Consent();

            if (adPersonalizationConsent != null)
            {
                offlineUserDataJob.CustomerMatchUserListMetadata.Consent.AdPersonalization =
                    (ConsentStatus)adPersonalizationConsent;
            }

            if (adUserDataConsent != null)
            {
                offlineUserDataJob.CustomerMatchUserListMetadata.Consent.AdUserData =
                    (ConsentStatus)adUserDataConsent;
            }
        }

        // Issues a request to create the offline user data job.
        CreateOfflineUserDataJobResponse response1 = service.CreateOfflineUserDataJob(
            customerId.ToString(), offlineUserDataJob);
        offlineUserDataJobResourceName = response1.ResourceName;
        Console.WriteLine($"Created an offline user data job with resource name: " +
            $"'{offlineUserDataJobResourceName}'.");
    } else {
        // Reuses the specified offline user data job.
        offlineUserDataJobResourceName =
            ResourceNames.OfflineUserDataJob(customerId, offlineUserDataJobId.Value);
    }

    AddOfflineUserDataJobOperationsRequest request =
        new AddOfflineUserDataJobOperationsRequest()
        {
            ResourceName = offlineUserDataJobResourceName,
            Operations = { BuildOfflineUserDataJobOperations() },
            EnablePartialFailure = true,
        };
    // Issues a request to add the operations to the offline user data job. This example
    // only adds a few operations, so it only sends one AddOfflineUserDataJobOperations
    // request.
    // If your application is adding a large number of operations, split the operations into
    // batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job.
    // See https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    // and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    // for more information on the per-request limits.
    AddOfflineUserDataJobOperationsResponse response2 =
        service.AddOfflineUserDataJobOperations(request);

    // Prints the status message if any partial failure error is returned.
    // Note: The details of each partial failure error are not printed here,
    // you can refer to the example HandlePartialFailure.cs to learn more.
    if (response2.PartialFailureError != null)
    {
        // Extracts the partial failure from the response status.
        GoogleAdsFailure partialFailure = response2.PartialFailure;
        Console.WriteLine($"{partialFailure.Errors.Count} partial failure error(s) " +
            $"occurred");
    }
    Console.WriteLine("The operations are added to the offline user data job.");

    if (!runJob)
    {
        Console.WriteLine($"Not running offline user data job " +
            "'{offlineUserDataJobResourceName}', as requested.");
        return offlineUserDataJobResourceName;
    }

    // Issues an asynchronous request to run the offline user data job for executing
    // all added operations.
    Operation<Empty, OfflineUserDataJobMetadata> operationResponse =
        service.RunOfflineUserDataJob(offlineUserDataJobResourceName);

    Console.WriteLine("Asynchronous request to execute the added operations started.");

    // Since offline user data jobs may take 24 hours or more to complete, it may not be
    // practical to do operationResponse.PollUntilCompleted() to wait for the results.
    // Instead, we save the offlineUserDataJobResourceName and use GoogleAdsService.Search
    // to check for the job status periodically.
    // In case you wish to follow the PollUntilCompleted or PollOnce approach, make sure
    // you keep both operationResponse and service variables alive until the polling
    // completes.

    return offlineUserDataJobResourceName;
}

PHP

private static function addUsersToCustomerMatchUserList(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    bool $runJob,
    ?string $userListResourceName,
    ?int $offlineUserDataJobId,
    ?int $adPersonalizationConsent,
    ?int $adUserDataConsent
) {
    $offlineUserDataJobServiceClient =
        $googleAdsClient->getOfflineUserDataJobServiceClient();

    if (is_null($offlineUserDataJobId)) {
        // Creates a new offline user data job.
        $offlineUserDataJob = new OfflineUserDataJob([
            'type' => OfflineUserDataJobType::CUSTOMER_MATCH_USER_LIST,
            'customer_match_user_list_metadata' => new CustomerMatchUserListMetadata([
                'user_list' => $userListResourceName
            ])
        ]);
        // Adds consent information to the job if specified.
        if (!empty($adPersonalizationConsent) || !empty($adUserDataConsent)) {
            $consent = new Consent();
            if (!empty($adPersonalizationConsent)) {
                $consent->setAdPersonalization($adPersonalizationConsent);
            }
            if (!empty($adUserDataConsent)) {
                $consent->setAdUserData($adUserDataConsent);
            }
            // Specifies whether user consent was obtained for the data you are uploading. See
            // https://www.google.com/about/company/user-consent-policy for details.
            $offlineUserDataJob->getCustomerMatchUserListMetadata()->setConsent($consent);
        }

        // Issues a request to create the offline user data job.
        /** @var CreateOfflineUserDataJobResponse $createOfflineUserDataJobResponse */
        $createOfflineUserDataJobResponse =
            $offlineUserDataJobServiceClient->createOfflineUserDataJob(
                CreateOfflineUserDataJobRequest::build($customerId, $offlineUserDataJob)
            );
        $offlineUserDataJobResourceName = $createOfflineUserDataJobResponse->getResourceName();
        printf(
            "Created an offline user data job with resource name: '%s'.%s",
            $offlineUserDataJobResourceName,
            PHP_EOL
        );
    } else {
        // Reuses the specified offline user data job.
        $offlineUserDataJobResourceName =
            ResourceNames::forOfflineUserDataJob($customerId, $offlineUserDataJobId);
    }

    // Issues a request to add the operations to the offline user data job. This example
    // only adds a few operations, so it only sends one AddOfflineUserDataJobOperations request.
    // If your application is adding a large number of operations, split the operations into
    // batches and send multiple AddOfflineUserDataJobOperations requests for the SAME job. See
    // https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    // and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    // for more information on the per-request limits.
    /** @var AddOfflineUserDataJobOperationsResponse $operationResponse */
    $response = $offlineUserDataJobServiceClient->addOfflineUserDataJobOperations(
        AddOfflineUserDataJobOperationsRequest::build(
            $offlineUserDataJobResourceName,
            self::buildOfflineUserDataJobOperations()
        )->setEnablePartialFailure(true)
    );

    // Prints the status message if any partial failure error is returned.
    // Note: The details of each partial failure error are not printed here, you can refer to
    // the example HandlePartialFailure.php to learn more.
    if ($response->hasPartialFailureError()) {
        // Extracts the partial failure from the response status.
        $partialFailure = GoogleAdsFailures::fromAny(
            $response->getPartialFailureError()->getDetails()->getIterator()->current()
        );
        printf(
            "%d partial failure error(s) occurred: %s.%s",
            count($partialFailure->getErrors()),
            $response->getPartialFailureError()->getMessage(),
            PHP_EOL
        );
    } else {
        print 'The operations are added to the offline user data job.' . PHP_EOL;
    }

    if ($runJob === false) {
        printf(
            "Not running offline user data job '%s', as requested.%s",
            $offlineUserDataJobResourceName,
            PHP_EOL
        );
        return;
    }

    // Issues an asynchronous request to run the offline user data job for executing all added
    // operations. The result is OperationResponse. Visit the OperationResponse.php file for
    // more details.
    $offlineUserDataJobServiceClient->runOfflineUserDataJob(
        RunOfflineUserDataJobRequest::build($offlineUserDataJobResourceName)
    );

    // Offline user data jobs may take 6 hours or more to complete, so instead of waiting
    // for the job to complete, retrieves and displays the job status once. If the job is
    // completed successfully, prints information about the user list. Otherwise, prints the
    // query to use to check the job again later.
    self::checkJobStatus($googleAdsClient, $customerId, $offlineUserDataJobResourceName);
}

Python

def add_users_to_customer_match_user_list(
    client: GoogleAdsClient,
    customer_id: str,
    user_list_resource_name: str,
    run_job: bool,
    offline_user_data_job_id: Optional[str],
    ad_user_data_consent: Optional[str],
    ad_personalization_consent: Optional[str],
) -> None:
    """Uses Customer Match to create and add users to a new user list.

    Args:
        client: The Google Ads client.
        customer_id: The ID for the customer that owns the user list.
        user_list_resource_name: The resource name of the user list to which to
            add users.
        run_job: If true, runs the OfflineUserDataJob after adding operations.
            Otherwise, only adds operations to the job.
        offline_user_data_job_id: ID of an existing OfflineUserDataJob in the
            PENDING state. If None, a new job is created.
        ad_user_data_consent: The consent status for ad user data for all
            members in the job.
        ad_personalization_consent: The personalization consent status for ad
            user data for all members in the job.
    """
    # Creates the OfflineUserDataJobService client.
    offline_user_data_job_service_client: OfflineUserDataJobServiceClient = (
        client.get_service("OfflineUserDataJobService")
    )
    offline_user_data_job_resource_name: str

    if offline_user_data_job_id:
        # Reuses the specified offline user data job.
        offline_user_data_job_resource_name = (
            offline_user_data_job_service_client.offline_user_data_job_path(
                customer_id, offline_user_data_job_id
            )
        )
    else:
        # Creates a new offline user data job.
        offline_user_data_job: OfflineUserDataJob = client.get_type(
            "OfflineUserDataJob"
        )
        offline_user_data_job.type_ = (
            client.enums.OfflineUserDataJobTypeEnum.CUSTOMER_MATCH_USER_LIST
        )
        offline_user_data_job.customer_match_user_list_metadata.user_list = (
            user_list_resource_name
        )

        # Specifies whether user consent was obtained for the data you are
        # uploading. For more details, see:
        # https://www.google.com/about/company/user-consent-policy
        if ad_user_data_consent:
            offline_user_data_job.customer_match_user_list_metadata.consent.ad_user_data = client.enums.ConsentStatusEnum[
                ad_user_data_consent
            ]
        if ad_personalization_consent:
            offline_user_data_job.customer_match_user_list_metadata.consent.ad_personalization = client.enums.ConsentStatusEnum[
                ad_personalization_consent
            ]

        # Issues a request to create an offline user data job.
        create_offline_user_data_job_response: (
            CreateOfflineUserDataJobResponse
        ) = offline_user_data_job_service_client.create_offline_user_data_job(
            customer_id=customer_id, job=offline_user_data_job
        )
        offline_user_data_job_resource_name = (
            create_offline_user_data_job_response.resource_name
        )
        print(
            "Created an offline user data job with resource name: "
            f"'{offline_user_data_job_resource_name}'."
        )

    # Issues a request to add the operations to the offline user data job.

    # Best Practice: This example only adds a few operations, so it only sends
    # one AddOfflineUserDataJobOperations request. If your application is adding
    # a large number of operations, split the operations into batches and send
    # multiple AddOfflineUserDataJobOperations requests for the SAME job. See
    # https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
    # and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
    # for more information on the per-request limits.
    request: AddOfflineUserDataJobOperationsRequest = client.get_type(
        "AddOfflineUserDataJobOperationsRequest"
    )
    request.resource_name = offline_user_data_job_resource_name
    request.operations = build_offline_user_data_job_operations(client)
    request.enable_partial_failure = True

    # Issues a request to add the operations to the offline user data job.
    response: AddOfflineUserDataJobOperationsResponse = (
        offline_user_data_job_service_client.add_offline_user_data_job_operations(
            request=request
        )
    )

    # Prints the status message if any partial failure error is returned.
    # Note: the details of each partial failure error are not printed here.
    # Refer to the error_handling/handle_partial_failure.py example to learn
    # more.
    # Extracts the partial failure from the response status.
    partial_failure: Union[status_pb2.Status, None] = getattr(
        response, "partial_failure_error", None
    )
    if getattr(partial_failure, "code", None) != 0:
        error_details: Iterable[Any, None] = getattr(
            partial_failure, "details", []
        )
        for error_detail in error_details:
            failure_message: GoogleAdsFailure = client.get_type(
                "GoogleAdsFailure"
            )
            # Retrieve the class definition of the GoogleAdsFailure instance
            # in order to use the "deserialize" class method to parse the
            # error_detail string into a protobuf message object.
            failure_object: GoogleAdsFailure = type(
                failure_message
            ).deserialize(error_detail.value)
            errors: Iterable[GoogleAdsError] = failure_object.errors

            for error in errors:
                print(
                    "A partial failure at index "
                    f"{error.location.field_path_elements[0].index} occurred.\n"
                    f"Error message: {error.message}\n"
                    f"Error code: {error.error_code}"
                )

    print("The operations are added to the offline user data job.")

    if not run_job:
        print(
            "Not running offline user data job "
            f"'{offline_user_data_job_resource_name}', as requested."
        )
        return

    # Issues a request to run the offline user data job for executing all
    # added operations.
    offline_user_data_job_service_client.run_offline_user_data_job(
        resource_name=offline_user_data_job_resource_name
    )

    # Retrieves and displays the job status.
    check_job_status(client, customer_id, offline_user_data_job_resource_name)

Ruby

def add_users_to_customer_match_user_list(client, customer_id, run_job, user_list, job_id, ad_user_data_consent, ad_personalization_consent)
  offline_user_data_service = client.service.offline_user_data_job

  job_name = if job_id.nil?
    # Creates the offline user data job.
    offline_user_data_job = client.resource.offline_user_data_job do |job|
      job.type = :CUSTOMER_MATCH_USER_LIST
      job.customer_match_user_list_metadata =
        client.resource.customer_match_user_list_metadata do |m|
          m.user_list = user_list

          if !ad_user_data_consent.nil? || !ad_personalization_consent.nil?
            m.consent = client.resource.consent do |c|
              # Specifies whether user consent was obtained for the data you are
              # uploading. For more details, see:
              # https://www.google.com/about/company/user-consent-policy
              unless ad_user_data_consent.nil?
                c.ad_user_data = ad_user_data_consent
              end
              unless ad_personalization_consent.nil?
                c.ad_personalization = ad_personalization_consent
              end
            end
          end
        end
    end

    # Issues a request to create the offline user data job.
    response = offline_user_data_service.create_offline_user_data_job(
      customer_id: customer_id,
      job: offline_user_data_job,
    )
    offline_user_data_job_resource_name = response.resource_name
    puts "Created an offline user data job with resource name: " \
      "#{offline_user_data_job_resource_name}"

    offline_user_data_job_resource_name
  else
    client.path.offline_user_data_job(customer_id, job_id)
  end

  # Issues a request to add the operations to the offline user data job. This
  # example only adds a few operations, so it only sends one
  # AddOfflineUserDataJobOperations request.  If your application is adding a
  # large number of operations, split the operations into batches and send
  # multiple AddOfflineUserDataJobOperations requests for the SAME job. See
  # https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
  # and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
  # for more information on the per-request limits.
  response = offline_user_data_service.add_offline_user_data_job_operations(
    resource_name: offline_user_data_job_resource_name,
    enable_partial_failure: true,
    operations: build_offline_user_data_job_operations(client),
  )

  # Prints errors if any partial failure error is returned.
  if response.partial_failure_error
    failures = client.decode_partial_failure_error(response.partial_failure_error)
    failures.each do |failure|
      failure.errors.each do |error|
        human_readable_error_path = error
          .location
          .field_path_elements
          .map { |location_info|
            if location_info.index
              "#{location_info.field_name}[#{location_info.index}]"
            else
              "#{location_info.field_name}"
            end
          }.join(" > ")

        errmsg =  "error occured while adding operations " \
          "#{human_readable_error_path}" \
          " with value: #{error.trigger.string_value}" \
          " because #{error.message.downcase}"
        puts errmsg
      end
    end
  end
  puts "The operations are added to the offline user data job."

  unless run_job
    puts "Not running offline user data job #{job_name}, as requested."
    return
  end

  # Issues an asynchronous request to run the offline user data job
  # for executing all added operations.
  response = offline_user_data_service.run_offline_user_data_job(
    resource_name: offline_user_data_job_resource_name
  )
  puts "Asynchronous request to execute the added operations started."
  puts "Waiting until operation completes."

  # Offline user data jobs may take 6 hours or more to complete, so instead of
  # waiting for the job to complete, retrieves and displays the job status
  # once. If the job is completed successfully, prints information about the
  # user list. Otherwise, prints the query to use to check the job again later.
  check_job_status(
    client,
    customer_id,
    offline_user_data_job_resource_name,
  )
end

Perl

sub add_users_to_customer_match_user_list {
  my ($api_client, $customer_id, $run_job, $user_list_resource_name,
    $offline_user_data_job_id, $ad_personalization_consent,
    $ad_user_data_consent)
    = @_;

  my $offline_user_data_job_service = $api_client->OfflineUserDataJobService();

  my $offline_user_data_job_resource_name = undef;
  if (!defined $offline_user_data_job_id) {
    # Create a new offline user data job.
    my $offline_user_data_job =
      Google::Ads::GoogleAds::V24::Resources::OfflineUserDataJob->new({
        type                          => CUSTOMER_MATCH_USER_LIST,
        customerMatchUserListMetadata =>
          Google::Ads::GoogleAds::V24::Common::CustomerMatchUserListMetadata->
          new({
            userList => $user_list_resource_name
          })});

    # Add consent information to the job if specified.
    if ($ad_personalization_consent or $ad_user_data_consent) {
      my $consent = Google::Ads::GoogleAds::V24::Common::Consent->new({});
      if ($ad_personalization_consent) {
        $consent->{adPersonalization} = $ad_personalization_consent;
      }
      if ($ad_user_data_consent) {
        $consent->{adUserData} = $ad_user_data_consent;
      }
      # Specify whether user consent was obtained for the data you are uploading.
      # See https://www.google.com/about/company/user-consent-policy for details.
      $offline_user_data_job->{customerMatchUserListMetadata}{consent} =
        $consent;
    }

    # Issue a request to create the offline user data job.
    my $create_offline_user_data_job_response =
      $offline_user_data_job_service->create({
        customerId => $customer_id,
        job        => $offline_user_data_job
      });
    $offline_user_data_job_resource_name =
      $create_offline_user_data_job_response->{resourceName};
    printf
      "Created an offline user data job with resource name: '%s'.\n",
      $offline_user_data_job_resource_name;
  } else {
    # Reuse the specified offline user data job.
    $offline_user_data_job_resource_name =
      Google::Ads::GoogleAds::V24::Utils::ResourceNames::offline_user_data_job(
      $customer_id, $offline_user_data_job_id);
  }

  # Issue a request to add the operations to the offline user data job.
  # This example only adds a few operations, so it only sends one AddOfflineUserDataJobOperations
  # request. If your application is adding a large number of operations, split
  # the operations into batches and send multiple AddOfflineUserDataJobOperations
  # requests for the SAME job. See
  # https://developers.google.com/google-ads/api/docs/remarketing/audience-types/customer-match#customer_match_considerations
  # and https://developers.google.com/google-ads/api/docs/best-practices/quotas#user_data
  # for more information on the per-request limits.
  my $user_data_job_operations = build_offline_user_data_job_operations();
  my $response                 = $offline_user_data_job_service->add_operations(
    {
      resourceName         => $offline_user_data_job_resource_name,
      enablePartialFailure => "true",
      operations           => $user_data_job_operations
    });

  # Print the status message if any partial failure error is returned.
  # Note: The details of each partial failure error are not printed here, you can
  # refer to the example handle_partial_failure.pl to learn more.
  if ($response->{partialFailureError}) {
    # Extract the partial failure from the response status.
    my $partial_failure = $response->{partialFailureError}{details}[0];
    printf "Encountered %d partial failure errors while adding %d operations " .
      "to the offline user data job: '%s'. Only the successfully added " .
      "operations will be executed when the job runs.\n",
      scalar @{$partial_failure->{errors}}, scalar @$user_data_job_operations,
      $response->{partialFailureError}{message};
  } else {
    printf "Successfully added %d operations to the offline user data job.\n",
      scalar @$user_data_job_operations;
  }

  if (!defined $run_job) {
    print
"Not running offline user data job $offline_user_data_job_resource_name, as requested.\n";
    return;
  }

  # Issue an asynchronous request to run the offline user data job for executing
  # all added operations.
  my $operation_response = $offline_user_data_job_service->run({
    resourceName => $offline_user_data_job_resource_name
  });

  # Offline user data jobs may take 6 hours or more to complete, so instead of waiting
  # for the job to complete, this example retrieves and displays the job status once.
  # If the job is completed successfully, it prints information about the user list.
  # Otherwise, it prints, the query to use to check the job status again later.
  check_job_status($api_client, $customer_id,
    $offline_user_data_job_resource_name);
}

curl

Supprimer des utilisateurs individuels à l'aide d'identifiants

Pour supprimer des utilisateurs individuels :

  • Définissez l'attribut remove d'un OfflineUserDataJobOperation sur un objet UserData.

  • Ajoutez un ou plusieurs UserIdentifier objets au champ répété user_identifiers[]. Un seul identifiant utilisateur peut être utilisé pour supprimer un utilisateur d'une liste, même si plusieurs identifiants correspondant à l'utilisateur ont été envoyés.

ou l'erreur standard.

Rechercher les échecs partiels

Lorsque vous ajoutez des opérations à votre tâche à l'aide de AddOfflineUserDataJobOperations, vous pouvez éventuellement activer l'échec partiel en définissant le champ enable_partial_failure sur true dans votre AddOfflineUserDataJobOperationsRequest.

Si l'échec partiel est activé, les opérations qui échouent à la validation sont enregistrées dans le champ partial_failure_error de la réponse, tandis que les opérations valides sont ajoutées à la tâche. Si l'échec partiel est désactivé (par défaut), toute opération qui échoue à la validation entraîne l'échec de l'ensemble de la requête. Pour en savoir plus, consultez le guide sur l'échec partiel.

Il est important de vérifier tout partial_failure_error dans la réponse lorsque l'échec partiel est activé. Si toutes vos opérations échouent à la validation, aucune ne sera ajoutée à la tâche, et partial_failure_error contiendra toutes les erreurs d'opération. Si vous appelez ensuite RunOfflineUserDataJob, la tâche se terminera immédiatement avec l'état SUCCESS car elle n'a aucune opération à traiter.

Supprimer toutes les données de la liste en une seule fois

Pour supprimer tous les utilisateurs d'une liste, définissez remove_all sur true dans un OfflineUserDataJobOperation, puis envoyez une requête RunOfflineUserDataJob avec le nom de ressource associé à l'opération remove_all.

Notez que lorsqu'une opération remove_all est incluse, elle doit être la première opération d'une tâche. Sinon, l'exécution de la tâche renvoie une INVALID_OPERATION_ORDER erreur. Pour remplacer complètement les membres d'une liste d'utilisateurs par de nouveaux membres, ordonnez les opérations dans AddOfflineUserDataJobOperationsRequest dans cette séquence :

  1. Définissez remove_all sur true dans un OfflineUserDataJobOperation.

  2. Pour chaque nouveau membre, ajoutez une opération create, en définissant son UserData dans un OfflineUserDataJobOperation.

Les opérations remove_all sont exécutées toutes les heures et peuvent durer jusqu'à 24 heures.

membership_life_spanOfflineUserDataJobOperation.remove_all

Recommandations pour l'actualisation des listes de clients

Vous pouvez récupérer des recommandations de type REFRESH_CUSTOMER_MATCH_LIST

pour identifier les listes de clients qui n'ont pas été mises à jour depuis un certain temps. Cela est particulièrement utile si vous êtes un annonceur tiers qui permet à ses utilisateurs de gérer des listes de clients.

Pour en savoir plus sur l'utilisation des recommandations, consultez le guide Score d'optimisation et recommandations.

Supprimer une liste

Utilisez la méthode UserListService.MutateUserLists pour envoyer une opération remove à l'aide du nom de ressource de la liste d'utilisateurs que vous souhaitez supprimer.

Mettre à jour une liste avec UserDataService

Le UserDataService est limité à 10 opérations et 100 user_identifiers au total par requête. Il est donc plus adapté aux petites mises à jour. Par exemple, si chacun de vos objets UserData comporte un UserIdentifier pour hashed_email et un autre UserIdentifier pour hashed_phone_number, votre requête peut contenir au maximum 50 objets UserData.

Le UserDataService contient la méthode UploadUserData, qui accepte un UploadUserDataRequest. En plus du customer_id, le UploadUserDataRequest accepte une liste d'opérations permettant de créer des contacts et un champ obligatoire appelé customer_match_user_list_metadata, qui est renseigné avec le nom de ressource de la liste de remarketing à cibler.

Commencez par créer une instance UploadUserDataRequest dans laquelle vous renseignez le customer_id et le customer_match_user_list_metadata :

Java

// Creates a request to add user data operations to the user list based on email addresses.
String userListResourceName = ResourceNames.userList(customerId, userListId);
UploadUserDataRequest.Builder uploadUserDataRequest =
   UploadUserDataRequest.newBuilder()
       .setCustomerId(String.valueOf(customerId))
       .setCustomerMatchUserListMetadata(
           CustomerMatchUserListMetadata.newBuilder()
               .setUserList(StringValue.of(userListResourceName))
               .build());

Pour importer les coordonnées de l'utilisateur, définissez CrmBasedUserListInfo.upload_key_type sur CONTACT_INFO.

Commencez par ajouter les opérations à l'objet UploadUserDataRequest. Chaque opération contient un champ create renseigné avec des objets UserData contenant une ou plusieurs instances UserIdentifier. Chaque UserIdentifier contient une information d'identification ou peut être l'un des différents types décrits ci-dessous.

Pour importer les adresses e-mail des clients, créez un nouveau UserDataOperation et renseignez son champ de création avec un objet UserData. L'objet UserData accepte une liste de user_identifiers. Renseignez le champ hashed_email avec les adresses e-mail des clients.

Java

ImmutableList<String> EMAILS =
  ImmutableList.of("client1@example.com", "client2@example.com", " Client3@example.com ");

// Hash normalized email addresses based on SHA-256 hashing algorithm.
List<UserDataOperation> userDataOperations = new ArrayList<>(EMAILS.size());
for (String email : EMAILS) {
 UserDataOperation userDataOperation =
     UserDataOperation.newBuilder()
         .setCreate(
             UserData.newBuilder()
                 .addUserIdentifiers(
                     UserIdentifier.newBuilder()
                        .setHashedEmail(StringValue.of(toSHA256String(email)))
                         .build())
                 .build())
         .build();
 userDataOperations.add(userDataOperation);
}
uploadUserDataRequest.addAllOperations(userDataOperations);

L'importation des address_info de l'utilisateur est semblable à l'importation de ses adresses e-mail. Toutefois, au lieu de transmettre un hashed_email, renseignez le champ address_info avec un objet OfflineUserAddressInfo contenant le first_name, le last_name, le country_code, et le postal_code de l'utilisateur. Comme les adresses e-mail, les first_name et last_name sont considérés comme des informations permettant d'identifier personnellement l'utilisateur et doivent être hachés avant d'être importés.

Java

String firstName = "Alex";
String lastName = "Quinn";
String countryCode = "US";
String postalCode = "94045";

UserIdentifier userIdentifierWithAddress =
   UserIdentifier.newBuilder()
       .setAddressInfo(
           OfflineUserAddressInfo.newBuilder()
               // First and last name must be normalized and hashed.
               .setHashedFirstName(
                   StringValue.of(toSHA256String(firstName)))
               .setHashedLastName(StringValue.of(toSHA256String(lastName)))
               // Country code and zip code are sent in plaintext.
               .setCountryCode(StringValue.of(countryCode))
               .setPostalCode(StringValue.of(postalCode))
               .build())
       .build();

UserDataOperation userDataOperation =
   UserDataOperation.newBuilder()
       .setCreate(
           UserData.newBuilder()
               .addUserIdentifiers(userIdentifierWithAddress)
               .build())
       .build();
uploadUserDataRequest.addOperations(userDataOperation);

Après avoir ajouté des opérations à l'instance UploadUserDataRequest, appelez la méthode uploadUserData sur le UserDataServiceClient pour envoyer la requête au serveur de l'API Google Ads. Vous pouvez vérifier si la requête a réussi en obtenant le nombre d'opérations et le temps d'importation dans l'objet de réponse. N'oubliez pas que la liste peut mettre plusieurs heures à être remplie avec des membres.

Java

// Creates the user data service client.
try (UserDataServiceClient userDataServiceClient =
   googleAdsClient.getLatestVersion().createUserDataServiceClient()) {
 // Add operations to the user list based on the user data type.
 UploadUserDataResponse response =
     userDataServiceClient.uploadUserData(uploadUserDataRequest.build());

 // Displays the results.
 // Reminder: it may take several hours for the list to be populated with members.
 System.out.printf(
     "Received %d operations at %s",
     response.getReceivedOperationsCount().getValue(),
     response.getUploadDateTime().getValue());
}

Changer le niveau de ciblage de la liste

Si vous devez modifier le niveau de ciblage de votre liste, par exemple en passant du ciblage au niveau du groupe d'annonces au ciblage au niveau de la campagne, consultez le guide Changer les niveaux de ciblage .

Examiner les performances de la liste

Pour collecter des données sur les performances de vos segments d'audience, envoyez une requête de recherche à la ressource ad_group_audience_view ou la ressource campaign_audience_view. Par exemple, vous pouvez examiner les conversions ou le cost_per_conversion pour déterminer si le ciblage du segment d'audience génère réellement plus de conversions, puis ajuster vos modificateurs d'enchères en conséquence.

SELECT
  ad_group_criterion.criterion_id,
  metrics.conversions,
  metrics.cost_per_conversion
FROM ad_group_audience_view

Nous vous recommandons d'attendre au moins deux semaines avant d'optimiser les enchères en fonction du volume de trafic du compte.