ניהול רשימות של לקוחות

במדריך הזה תמצאו מידע על עדכונים של רשימות לקוחות, הסרתם ודיווח על רשימות של לקוחות.

עדכון רשימה באמצעות OfflineUserDataJobService

אחרי שיוצרים את רשימות הלקוחות ומגדירים טירגוט, מומלץ לעדכן אותן באופן קבוע.

כדי לעדכן את הרשימות בנתונים העדכניים ביותר, בדרך כלל עדיף לצרף או להסיר משתמשים בודדים מאשר להסיר את כל המשתמשים מהרשימה ולהעלות אותם מאפס.

הוספה לרשימה

כדי להוסיף לרשימה קיימת יוצרים OfflineUserDataJob, בדיוק כמו שיוצרים רשימת לקוחות חדשה.

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

AddCustomerMatchUserList.java

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.V16.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;
}
AddCustomerMatchUserList.cs

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);
}
AddCustomerMatchUserList.php

Python

def add_users_to_customer_match_user_list(
    client,
    customer_id,
    user_list_resource_name,
    run_job,
    offline_user_data_job_id,
    ad_user_data_consent,
    ad_personalization_consent,
):
    """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 = client.get_service(
        "OfflineUserDataJobService"
    )

    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 = 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 = (
            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 = 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 = 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 = getattr(response, "partial_failure_error", None)
    if getattr(partial_failure, "code", None) != 0:
        error_details = getattr(partial_failure, "details", [])
        for error_detail in error_details:
            failure_message = 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 = type(failure_message).deserialize(
                error_detail.value
            )

            for error in failure_object.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)
add_customer_match_user_list.py

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
add_customer_match_user_list.rb

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::V16::Resources::OfflineUserDataJob->new({
        type                          => CUSTOMER_MATCH_USER_LIST,
        customerMatchUserListMetadata =>
          Google::Ads::GoogleAds::V16::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::V16::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::V16::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);
}
add_customer_match_user_list.pl

הסרת משתמשים ספציפיים באמצעות מזהים

כדי להסיר משתמשים ספציפיים:

  • מגדירים את המאפיין remove באובייקט OfflineUserDataJobOperation ששווה לאובייקט UserData.

  • מוסיפים אובייקט UserIdentifier אחד או יותר לשדה user_identifiers[] שחוזר על עצמו. אפשר להשתמש במזהה משתמש יחיד כדי להסיר משתמש מהרשימה, גם אם נשלחו יותר ממזהה אחד שתואם למשתמש.

הסרת כל הנתונים מהרשימה בבת אחת

על מנת להסיר את כל המשתמשים מהרשימה, צריך להגדיר את remove_all לערך true בשדה OfflineUserDataJobOperation, ולאחר מכן ליצור בקשת RunOfflineUserDataJob עם שם המשאב שמשויך לפעולה remove_all.

שימו לב שכאשר נכללת פעולה remove_all, היא חייבת להיות הפעולה הראשונה במשימה. אחרת, הרצת המשימה תחזיר את השגיאה INVALID_OPERATION_ORDER. כדי להחליף לחלוטין את החברים ברשימת משתמשים בחברים חדשים, סדר את הפעולות ב-AddOfflineUserDataJobOperationsRequest לפי הרצף הבא:

  1. מגדירים את remove_all לערך true ב-OfflineUserDataJobOperation.

  2. לכל חבר חדש צריך להוסיף פעולת create ולהגדיר את ה-UserData שלו ב-OfflineUserDataJobOperation.

פעולות של remove_all מבוצעות מדי שעה, והן יכולות לפעול עד 24 שעות.

המלצות לרענון של רשימת הלקוחות

אפשר לאחזר המלצות מסוג REFRESH_CUSTOMER_MATCH_LIST כדי לזהות רשימות של לקוחות שלא עודכנו במשך זמן מה. זו אפשרות שימושית במיוחד למפרסמים מצד שלישי שמאפשרים למשתמשים לנהל רשימות של לקוחות.

מידע נוסף על שימוש בהמלצות זמין במדריך ציון האופטימיזציה וההמלצות.

הסרת רשימה

משתמשים ב-method UserListService.mutate_user_lists כדי לשלוח פעולה remove באמצעות שם המשאב של רשימת המשתמשים שרוצים להסיר.

עדכון רשימה באמצעות UserDataService

ל-UserDataService יש מגבלה של 10 פעולות ו-100 user_identifiers בסה"כ לכל בקשה, כך שהוא מתאים יותר לעדכונים קטנים. לדוגמה, אם בכל אחד מהאובייקטים ב-UserData יש UserIdentifier אחד עבור hashed_email ו-UserIdentifier אחר עבור hashed_phone_number, הבקשה שלך יכולה להכיל עד 50 אובייקטים מסוג UserData.

UserDataService מכיל את השיטה UploadUserData, שמקבלת את הערך UploadUserDataRequest. בנוסף ל-customer_id, השדה UploadUserDataRequest מקבל רשימת פעולות ליצירת אנשי קשר ושדה חובה בשם customer_match_user_list_metadata, שמאוכלס בשם המשאב של רשימת הרימרקטינג שצריך לטרגט.

מתחילים ביצירת מכונה UploadUserDataRequest שבה מאכלסים את customer_id ואת 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());

כדי להעלות פרטים ליצירת קשר של משתמשים, צריך להגדיר את CrmBasedUserListInfo.upload_key_type לערך CONTACT_INFO.

תחילה, מוסיפים את הפעולות לאובייקט UploadUserDataRequest. כל פעולה מכילה שדה create שמאוכלס באובייקטים UserData שמחזיקים במכונה אחת או יותר של UserIdentifier. כל UserIdentifier מכיל פרט אחד של מידע מזהה או יכול להיות אחד מכמה סוגים שונים, מתואר כל אחד מהם בהמשך.

כדי להעלות כתובות אימייל של לקוחות, צריך ליצור UserDataOperation חדש ולאכלס את שדה היצירה שלו באובייקט UserData. האובייקט UserData מקבל רשימה של user_identifiers. מאכלסים את השדה hashed_email בכתובות האימייל של הלקוח.

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

העלאת המשתמש address_info דומה להעלאת כתובות אימייל של משתמשים. עם זאת, במקום להעביר hashed_email, מאכלסים את השדה address_info באובייקט OfflineUserAddressInfo שמכיל את השדות first_name, last_name, country_code ו-postal_code של המשתמש. בדומה לכתובות אימייל, first_name ו-last_name נחשבים לפרטים אישיים מזהים וצריך לבצע גיבוב (hash) לפני ההעלאה.

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

אחרי שמוסיפים פעולות למכונה UploadUserDataRequest, צריך להפעיל את השיטה uploadUserData ב-UserDataServiceClient כדי לשלוח את הבקשה לשרת של Google Ads API. על ידי הצגת מספר הפעולות וזמן ההעלאה באובייקט התגובה אפשר לראות אם הבקשה בוצעה בהצלחה. חשוב לזכור שייתכן שיחלפו כמה שעות עד שהרשימה תתמלא בחברים.

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

שינוי רמת הטירגוט של הרשימות

אם אתם צריכים לשנות את רמת הטירגוט ברשימה, למשל מטירגוט ברמת קבוצת המודעות לרמת הקמפיין, תוכלו להיעזר במדריך בנושא החלפת רמות מיקוד.

בדיקת הביצועים של רשימות

כדי לאסוף נתוני ביצועים של פלחי קהל היעד, צריך לשלוח בקשת חיפוש למשאב ad_group_audience_view או למשאב campaign_audience_view. לדוגמה, כדאי לעיין בערכים conversions או cost_per_conversion כדי לקבוע אם טירגוט לפלח של קהל היעד מוביל בפועל להמרות, ולשנות את ההתאמות של הצעות המחיר בהתאם.

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

מומלץ להמתין לפחות שבועיים לפני שמבצעים אופטימיזציה של הצעות מחיר על סמך נפח התנועה.