Asset posizione

A differenza di altri asset, gli asset posizione vengono creati automaticamente dall'API Google Ads dopo la creazione di un insieme di asset. Per prima cosa, crea un insieme di asset di sincronizzazione della posizione e collegalo al cliente. Poi, se devi selezionare un sottoinsieme degli asset posizione nell'insieme di asset per una campagna o un gruppo di annunci, crea un insieme di asset del gruppo di località e collegalo alla campagna o al gruppo di annunci.

Creare un insieme di asset di sincronizzazione della posizione e collegarlo al cliente

  1. Crea un insieme di asset di sincronizzazione della posizione.
  2. Collegalo a un cliente utilizzando CustomerAssetSetService.

Creare un insieme di asset di sincronizzazione della posizione

  1. Crea un nuovo AssetSet.
    1. Imposta type su LOCATION_SYNC.
    2. Imposta location_set su un nuovo LocationSet.

  2. Nel nuovo LocationSet:

    1. Imposta location_ownership_type in base al tuo caso d'uso:
      • Imposta BUSINESS_OWNER se possiedi la sede dell'attività.
      • Imposta AFFILIATE se non possiedi la sede dell'attività, ma vendi i tuoi prodotti lì.

    2. Imposta il campo oneof source in base al tuo caso d'uso:

      • Imposta business_profile_location_set se vuoi eseguire la sincronizzazione con le sedi nel tuo account Profilo dell'attività su Google.

        Quando crei un BusinessProfileLocationSet per collegare Google Ads a un account Profilo dell'attività su Google, devi fornire un token di accesso OAuth 2.0 nel campo http_authorization_token. Questo token funge da prova che stai autorizzando Google Ads ad accedere ai dati sulla posizione del Profilo dell'attività su Google specificato.

        Il token deve soddisfare questi requisiti:

        • Deve essere generato per l'Account Google (utente o account di servizio) il cui indirizzo email è fornito nel campo email_address di BusinessProfileLocationSet.
        • Questo account deve disporre di autorizzazioni sufficienti per leggere le sedi dell'attività all'interno del Profilo dell'attività su Google.
        • Il token OAuth 2.0 deve essere ottenuto con l'ambito https://www.googleapis.com/auth/business.manage.

        Per istruzioni dettagliate su come generare un token di accesso OAuth 2.0, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.

      • Imposta chain_location_set se vuoi eseguire la sincronizzazione con le sedi negli ID catena specificati.

      • Imposta maps_location_set se vuoi aggiungere manualmente le sedi utilizzando gli ID luogo.

Una volta completati questi passaggi, l'API Google Ads genera asset posizione e li aggiunge all'insieme di asset di sincronizzazione della posizione creato, in modo simile a quando lo fai manualmente utilizzando AssetSetAssetService. Non devi manipolarli, a meno che tu non voglia aggiungere manualmente a un insieme di asset del gruppo di località statico.

Per un cliente può esistere un solo insieme di asset di sincronizzazione della posizione attivo con status impostato su ENABLED. Se devi creare un altro tipo di insieme di asset di sincronizzazione della posizione, rimuovi prima quello esistente.

Collegare l'insieme di asset di sincronizzazione della posizione a un cliente

Utilizza CustomerAssetSetService.MutateCustomerAssetSets per collegare l'insieme di asset di sincronizzazione della posizione nella sezione precedente al tuo cliente.

(Facoltativo) Creare un insieme di asset del gruppo di località e collegarlo a una campagna o a un gruppo di annunci

Un insieme di asset del gruppo di località è necessario solo se devi selezionare un sottoinsieme di asset posizione. Questo perché le campagne e i gruppi di annunci ereditano gli asset posizione a livello di cliente.

Gli insiemi di asset del gruppo di località contengono un sottoinsieme di asset posizione dell'insieme di asset di sincronizzazione della posizione. Puoi creare dinamicamente un insieme di asset del gruppo di località sfruttando alcune funzionalità di Profilo dell'attività su Google (ad esempio il filtro per etichette) o gli ID catena e le sedi della catena. In alternativa, puoi creare staticamente un insieme di asset del gruppo di località.

  1. Crea un insieme di asset del gruppo di località. L'insieme di asset del gruppo di località può essere dinamico o statico.
  2. Collega l'insieme di asset a una campagna o a un gruppo di annunci, a seconda delle tue esigenze.
  3. (Facoltativo) Aggiungi gli asset generati in precedenza all'insieme di asset del gruppo di località statico appena creato.

Per un determinato cliente, puoi creare più insiemi di asset del gruppo di località dinamici o statici.

Creare un insieme di asset del gruppo di località

Crea un nuovo AssetSet e imposta location_group_parent_asset_set_id sull'ID dell'insieme di asset di sincronizzazione della posizione creato in precedenza.

Poi, imposta alcuni campi a seconda che tu voglia creare un insieme di asset del gruppo di località dinamico o statico.

Insiemi di asset dinamici

A seconda del campo che hai impostato in LocationSet, imposta i campi in base alla seguente regola:

Se imposti il seguente campo Poi imposta tipo su E imposta questo campo come campo oneof asset_set_source
business_profile_location_set BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP business_profile_location_group
chain_location_set CHAIN_DYNAMIC_LOCATION_GROUP chain_location_group

Se imposti maps_location_set durante la creazione dell'insieme di asset di sincronizzazione della posizione set, non potrai creare un insieme di asset del gruppo di località dinamico. Questo perché hai aggiunto manualmente le sedi tramite gli ID luogo e non sono disponibili funzionalità di filtro per questo tipo di sedi.

Insiemi di asset statici

Imposta type su STATIC_LOCATION_GROUP. Puoi creare insiemi di asset del gruppo di località statici per qualsiasi tipo di insieme di asset di sincronizzazione della posizione, indipendentemente dai campi (business_profile_location_set, chain_location_set, o maps_location_set) impostati in the LocationSet.

Per gli insiemi di asset del gruppo di località statici, devi aggiungere manualmente gli asset posizione generati agli insiemi di asset del gruppo di località sets.

Collegare l'insieme di asset a una campagna o a un gruppo di annunci

Utilizza CampaignAssetSetService.MutateCampaignAssetSets per collegare l'insieme di asset del gruppo di località alla tua campagna.

In alternativa, utilizza AdGroupAssetSetService.MutateAdGroupAssetSets se vuoi collegare l'insieme di asset del gruppo di località a un gruppo di annunci.

(Facoltativo) Aggiungere gli asset posizione all'insieme di asset del gruppo di località statico

Questo passaggio è obbligatorio solo se hai creato in precedenza un insieme di asset del gruppo di località statico.

  1. Utilizza il report asset_set_asset per recuperare i nomi delle risorse degli asset generati automaticamente per l' insieme di asset di sincronizzazione della posizione creato in precedenza. Utilizza il filtro per recuperare solo gli asset che ti interessano.
  2. Aggiungili all'insieme di asset del gruppo di località statico utilizzando AssetSetAssetService.MutateAssetSetAssets.

Gestire gli ID località del Profilo dell'attività

Quando utilizzi un business_profile_location_set e filtri in base a listing_id_filters recuperati dal sito web o dall'API del Profilo dell'attività, potrebbe essere necessario convertire questi valori numerici dal tipo uint64 a int64. Se il tuo codice genera un errore di runtime che indica che l'ID località del Profilo dell'attività è fuori intervallo quando lo aggiungi al campo ripetuto listing_id_filters[], probabilmente devi convertirlo utilizzando uno dei seguenti esempi:

Java

/**
 * Converts the business profile location ID to the format expected by the
 * DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
 * The business profile location ID is an unsigned 64-bit integer, while the
 * listing_id_filters[] field expects signed 64-bit integers. This means that
 * for business profile location IDs that are out of range, we must perform the
 * two's complement to convert it into a signed int.
 *
 * @param businessProfileLocationId The ID of a Business Profile location ID.
 * @return a Business Profile location ID as a signed 64-bit integer (long).
 */
public static long convertBusinessProfileLocationId(String businessProfileLocationId) {
    return Long.parseUnsignedLong(businessProfileLocationId);
}

C#

/// <summary>
/// Converts the business profile location ID to the format expected by the
/// DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
/// The business profile location ID is an unsigned 64-bit integer, while the
/// listing_id_filters[] field expects signed 64-bit integers. This means that
/// for business profile location IDs that are out of range, we must perform the
/// two's complement to convert it into a signed int.
/// </summary>
/// <param name="businessProfileLocationId">The ID of a Business Profile location.</param>
/// <returns>The converted business location ID in signed 64 bit.</returns>
public long ConvertBusinessProfileLocationId(ulong businessProfileLocationId)
{
  return unchecked((long)businessProfileLocationId);
}

PHP

/**
* Converts a business profile location ID to a signed 64 bit integer.
*
* Converts the business profile location ID to the format expected by the
* DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
* The business profile location ID is an unsigned 64-bit integer, while the
* listing_id_filters[] field expects signed 64-bit integers. This means that
* for business profile location IDs that are out of range, we must perform the
* two's complement to convert it into a signed int.
*
* @param string $businessProfileLocationId the ID of a Business Profile location
* @return int the converted business location ID in signed 64 bit
*/
public static function convertBusinessProfileLocationId(string $businessProfileLocationId): int
{
    $unsignedMax = '18446744073709551615'; // 2^64 - 1
    $signedMax = '9223372036854775807'; // 2^63 - 1

    // Check if the business profile location ID is within 64 bit range.
    // If not, throw an error.
    if (bccomp($businessProfileLocationId, '0') < 0 || bccomp($businessProfileLocationId, $unsignedMax) > 0) {
        throw new InvalidArgumentException(
            'The given business profile location id is outside of the range for a 64 bit integer.'
        );
    }

    // Check if the business profile location ID is in signed 64 bit range.
    // If it's not, convert it to its two's complement.
    if (bccomp($businessProfileLocationId, $signedMax) > 0) {
        // Two's complement: ID - 2^64
        return (int) bcsub($businessProfileLocationId, '18446744073709551616');
    }

    return (int) $businessProfileLocationId;
}

Python

import ctypes

def convert_business_profile_location_id(business_profile_location_id):
    """Converts a business profile location ID to a signed 64 bit integer.

    Converts the business profile location ID to the format expected by the
    DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
    The business profile location ID is an unsigned 64-bit integer, while the
    listing_id_filters[] field expects signed 64-bit integers. This means that
    for business profile location IDs that are out of range, we must perform the
    two's complement to convert it into a signed int.

    Args:
        business_profile_location_id: the ID of a Business Profile location ID.

    Returns:
        a Business Profile location ID as a signed 64 bit integer.
    """
    # Check if the business profile location ID is within 64 bit range.
    # If not, throw an error.
    if business_profile_location_id < 0 or business_profile_location_id >= 2 ** 64:
        raise ValueError(
            "The given business profile location id is outside of the range for a 64 bit integer."
        )
    # Check if the business profile location ID is in signed 64 bit range.
    # If it's not, convert it to its two's complement.
    elif business_profile_location_id >= 2 ** 63:
        return ctypes.c_int64(business_profile_location_id).value
    else:
        return business_profile_location_id

Ruby

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
# Since Ruby supports arbitrary precision numbers, we have to calculate it
# manually.
LONG_MAX = 2 ** 63
ULONG_MAX = LONG_MAX * 2
def convert_business_profile_location_id(business_profile_location_id)
  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if business_profile_location_id < 0 || business_profile_location_id >= 2 ** 64
    raise "The given business profile location id is outside of the range for a 64 bit integer."
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  elsif business_profile_location_id >= 2**63
    -1 * (ULONG_MAX - business_profile_location_id)
  else
    business_profile_location_id
  end
end

Perl

use bigint;

# Converts the business profile location ID to the format expected by the
# DynamicBusinessProfileLocationGroupFilter.listing_id_filters[] repeated field.
# The business profile location ID is an unsigned 64-bit integer, while the
# listing_id_filters[] field expects signed 64-bit integers. This means that
# for business profile location IDs that are out of range, we must perform the
# two's complement to convert it into a signed int.
sub convert_business_profile_location_id {
  my ($business_profile_location_id) = @_;

  # Check if the business profile location ID is within 64 bit range.
  # If not, throw an error.
  if ($business_profile_location_id < 0 || $business_profile_location_id >= 2**64) {
    die "The given business profile location id is outside of the range for a 64 bit integer";
  # Check if the business profile location ID is in signed 64 bit range.
  # If it's not, convert it to its two's complement.
  } elsif ($business_profile_location_id >= 2**63) {
    return -1 * (2**64 - $business_profile_location_id);
  } else {
    return $business_profile_location_id;
  }
}
Indietro
Creazione e utilizzo
Avanti
Asset automatici