Aggiungi nuove conversioni

Quando posso utilizzare i dati caricati?

Se specifichi un conversionTimestamp di oggi o di ieri per una conversione, le metriche per questa conversione verranno visualizzate nell'interfaccia utente di Search Ads 360 entro un'ora dal caricamento. Se specifichi un conversionTimestamp precedente a ieri, le metriche verranno aggiornate tra diverse ore.

Converti tutti i timestamp per le conversioni in ora dell'epoca (nota anche come ora Unix).

Posso creare attività Floodlight dall'API?

Se l'inserzionista non ha ancora creato un'attività Floodlight per il monitoraggio delle conversioni offline, puoi utilizzare l'API Campaign Manager per crearne una. Non puoi utilizzare l'API per specificare che un'attività Floodlight viene utilizzata principalmente per le conversioni offline, che è una buona prassi quando le strategie di offerta utilizzeranno i dati della conversione.

Ti consigliamo che dopo aver utilizzato l'API per creare un'attività Floodlight, un utente Search Ads 360 acceda a Search Ads 360 e modifichi l'impostazione dell'attività in modo da indicare che l'attività offline è la fonte principale delle conversioni.

Best practice per l'aggiunta di conversioni

Consigliamo le seguenti best practice per l'aggiunta di conversioni:

1. Chiedi a un utente Search Ads 360 di accedere a Search Ads 360 e di modificare le impostazioni per ogni attività Floodlight utilizzata per generare report sulle conversioni offline. Le impostazioni devono indicare che la sorgente principale delle conversioni è l'attività offline. Per istruzioni, consulta il Centro assistenza Search Ads 360.

2. Carica le conversioni non appena sono disponibili. Se attribuisci le conversioni a determinate visite, attendi almeno 6 ore dopo la visita prima di caricare la conversione. Search Ads 360 potrebbe non riconoscere l'ID clic della visita se carichi prima di 6 ore dalla visita. In rari casi, potresti dover attendere fino a 24 ore prima che Search Ads 360 possa riconoscere l'ID clic.

   Assicurati che ogni caricamento contenga le conversioni più recenti. All'interno di una singola richiesta di caricamento, non è un problema se le voci non sono in ordine cronologico. Tuttavia, una strategia di offerta potrebbe non essere in grado di prendere in considerazione le conversioni più datate caricate in un momento successivo nel corso di un'altra richiesta.

Inviare una richiesta di inserimento

Puoi inviare una richiesta Conversion.insert() per eseguire una delle seguenti operazioni:

• Attribuire una conversione a una visita specifica
• Attribuire una conversione solo a una parola chiave

I campi obbligatori in una richiesta Conversion.insert() dipendono dall'evento o dall'elemento a cui stai attribuendo la conversione. Le sezioni seguenti elencano i campi obbligatori e facoltativi per ogni evento o elemento a cui puoi attribuire una conversione.

Attribuire una conversione a una visita specifica

Quando un cliente fa clic su uno o più annunci e arriva sul sito di un inserzionista, Search Ads 360 considera la sessione utente sul sito dell'inserzionista come una visita. Per attribuire una conversione a una visita, specifica quanto segue nella richiesta Conversion.insert()

Campi obbligatori

• clickId: l'ID clic della visita sensibile alle maiuscole. Cerca l'ID clic o le conversioni elenco nei log web dell'inserzionista e utilizza un ID clic di un'altra conversione. Search Ads 360 attribuirà la conversione alla parola chiave, all'annuncio e ad altri oggetti Search Ads 360 responsabili della generazione della visita.
  Attendi almeno 6 ore dopo che Search Ads 360 ha generato un ID clic per caricare le conversioni. Se ricevi l'errore "ID clic non trovato", attendi 24 ore e carica di nuovo le conversioni. Tutte le conversioni devono essere caricate entro 90 giorni dalla data di generazione dell'ID clic. In caso contrario, l'API Search Ads 360 potrebbe non riconoscere la visita.
• conversionId: per le conversioni offline, gli inserzionisti forniscono questo ID. Gli inserzionisti possono specificare qualsiasi ID significativo per loro. Ogni conversione in una richiesta deve specificare un ID univoco e la combinazione di ID e timestamp deve essere univoca tra tutte le conversioni dell'inserzionista. Per le conversioni online, Search Ads 360 copia dsConversionId o floodlightOrderId in questa proprietà in base alle istruzioni Floodlight dell'inserzionista.
• conversionTimestamp: indica la data e l'ora in cui si è verificata la conversione. Ad esempio, se la conversione avviene il 05 ago 2016 alle ore 11:53:22 (ora legale orientale degli Stati Uniti) (GMT-4:00), specifica il timestamp in millisecondi dall'epoca: 1470412402000.
• segmentationType: specifica il tipo di sistema di conversione a cui stai caricando la conversione. Al momento sono supportate solo le conversioni Floodlight, pertanto in questo campo è sempre obbligatorio specificare FLOODLIGHT.
• segmentationName: il nome dell'attività Floodlight utilizzata dall'inserzionista per registrare la conversione.

  Se il tuo inserzionista contiene attività con lo stesso nome (ciò può accadere se le attività appartengono a gruppi Floodlight diversi), l'azione consigliata è rinominare una delle attività.

  In alternativa, se conosci l'ID assegnato da Search Ads 360 a un'attività Floodlight, puoi specificarlo in segmentationId anziché il nome nel campo segmentationName. Anche Campaign Manager assegna un ID all'attività Floodlight, ma l'ID di Campaign Manager è diverso dall'ID di Search Ads 360 e non può essere utilizzato per attribuire le conversioni. Per visualizzare l'ID Search Ads 360 per un'attività Floodlight, scarica un report sulle conversioni (dall'interfaccia utente di Search Ads 360 o dall'API di reporting). Se almeno una conversione è stata attribuita all'attività Floodlight durante il periodo di tempo del report, nel report viene visualizzato l'ID Search Ads 360.

• type: il tipo di conversione, ovvero ACTION o TRANSACTION. Una conversione di tipo AZIONE non ha valore monetario, mentre una conversione di tipo TRANSAZIONE sì. Alcuni esempi sono le registrazioni alla mailing list (AZIONE) rispetto agli acquisti e-commerce (TRANSAZIONE).

  Se specifichi TRANSACTION, devi specificare anche il seguente campo:

  • revenueMicros: il valore monetario della conversione.

Campi facoltativi

• quantityMillis: il numero di elementi in questa conversione. Ad esempio, il numero di persone che si sono iscritte a una newsletter via email o la quantità totale di articoli venduti. Se non specifichi questo campo per le conversioni di tipo Azione, Search Ads 360 inserisce automaticamente un valore di 1000.
• currencyCode: la valuta delle entrate di una transazione. Per impostazione predefinita, si presume che le entrate siano espresse nella valuta dell'inserzionista. Se specifichi una valuta diversa, Search Ads 360 converte l'importo delle entrate specificato nella valuta dell'inserzionista. Scopri di più
  Utilizza il formato alfabetico ISO 4217 (3 caratteri) per specificare la valuta.
  Valido solo per le conversioni di tipo TRANSAZIONE.
• customMetric e customDimension: caricano dati aggiuntivi su una conversione, ad esempio il paese in cui viene spedito un articolo acquistato, gli ID prodotto o persino la durata di una chiamata. Scopri di più sul caricamento dei dati per le variabili Floodlight personalizzate.
• deviceType: specifica il tipo di dispositivo su cui è avvenuta la conversione. Consulta l'elenco dei valori accettati per questo campo.

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "revenueMicros": "10000000", // 10 million revenueMicros is equivalent to $10 of revenue
    "currencyCode": "USD"
  }]
}
          

  /**
   * Instantiate the Doubleclicksearch service, create conversions, and upload them.
   */
  public static void main(String[] args) throws Exception {

    Doubleclicksearch service = getService(); // See Set Up Your Application.

    // Set up a List to keep track of each conversion you create.
    List<Conversion> conversions = new Vector<Conversion>();

    // Add a conversion to the List.
    addTransactionConversionForVisit(conversions, "COiYmPDTv7kCFcP0KgodOzQAAA", // Replace with a click ID from your site
        "test_" + System.currentTimeMillis(), 10000000L, 1378710000000L);

    // Upload the List and handle the response.
    uploadConversions(conversions, service);
  }


  /**
   * Create a TRANSACTION conversion and add it to a List<Conversion>. This sample hard-codes
   * the segmentation name and currency. You probably wouldn't want your production code to be so brittle.
   */
  private static List<Conversion> addTransactionConversionForVisit(List<Conversion> conversions,
      String clickId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion().setClickId(clickId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }


  /**
   * Convert the List of conversions to a DS ConversionList, send an insert request to DS,
   * and output the response to a file.
   */
  private static void uploadConversions(List<Conversion> conversions, Doubleclicksearch service)
      throws IOException {

    FileOutputStream outputStream =
        new FileOutputStream(new File("./", "InsertConversionsResponse.txt"));
    final PrintStream printStream = new PrintStream(outputStream);

    try {
      // Convert the List to a ConversionList.
      ConversionList conversionList = new ConversionList().setConversion(conversions);

      // Insert an upload request and download the response to a file.
      service.conversion().insert(conversionList).executeAndDownloadTo(printStream);
      printStream.close();
    } catch (GoogleJsonResponseException e) {
      System.err.println("Get request was rejected.");
      for (ErrorInfo error : e.getDetails().getErrors()) {
        System.err.println(error.getMessage());
      }
      System.exit(e.getStatusCode());
    }
  }
            

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a visit.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'clickId': 'COiYmPDTv7kCFcP0KgodOzQAAA', // Replace with a click ID from your site
              'conversionId': 'test_20140206_00',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '10000000', // 10 million revenueMicros is equivalent to $10 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

Attribuire una conversione solo a una parola chiave

Se la tua preoccupazione principale è attribuire le conversioni alle parole chiave e non ti interessa l'attribuzione agli annunci, puoi omettere la maggior parte degli identificatori di Search Ads 360 e specificare solo l'identificatore della parola chiave insieme ad alcuni altri campi:

Campi obbligatori

• criterionId: questo è l'identificatore della parola chiave. Puoi ottenere il valore criterionId aggiungendo la macro TrackerId agli URL pagina di destinazione. Per informazioni su come ottenere gli ID parola chiave, consulta ID e conversioni di Search Ads 360.
• conversionId: per le conversioni offline, gli inserzionisti forniscono questo ID. Gli inserzionisti possono specificare qualsiasi ID significativo per loro. Ogni conversione in una richiesta deve specificare un ID univoco e la combinazione di ID e timestamp deve essere univoca tra tutte le conversioni dell'inserzionista. Per le conversioni online, Search Ads 360 copia dsConversionId o floodlightOrderId in questa proprietà in base alle istruzioni Floodlight dell'inserzionista.
• conversionTimestamp: indica la data e l'ora in cui si è verificata la conversione. Ad esempio, se la conversione avviene il 05 ago 2016 alle ore 11:53:22 (ora legale orientale degli Stati Uniti) (GMT-4:00), specifica il timestamp in millisecondi dall'epoca: 1470412402000.
• segmentationType: specifica il tipo di sistema di conversione a cui stai caricando la conversione. Al momento sono supportate solo le conversioni Floodlight, pertanto in questo campo è sempre obbligatorio specificare FLOODLIGHT.
• segmentationName: il nome dell'attività Floodlight utilizzata dall'inserzionista per registrare la conversione.

  Se il tuo inserzionista contiene attività con lo stesso nome (ciò può accadere se le attività appartengono a gruppi Floodlight diversi), l'azione consigliata è rinominare una delle attività.

  In alternativa, se conosci l'ID assegnato da Search Ads 360 a un'attività Floodlight, puoi specificarlo in segmentationId anziché il nome nel campo segmentationName. Anche Campaign Manager assegna un ID all'attività Floodlight, ma l'ID di Campaign Manager è diverso dall'ID di Search Ads 360 e non può essere utilizzato per attribuire le conversioni. Per visualizzare l'ID Search Ads 360 di un'attività Floodlight, scarica un report sulle conversioni (dall'interfaccia utente di Search Ads 360 o dall'API reporting). Se almeno una conversione è stata attribuita all'attività Floodlight durante il periodo di tempo del report, nel report viene visualizzato l'ID Search Ads 360.

• type: il tipo di conversione, ovvero ACTION o TRANSACTION. Una conversione di tipo AZIONE non ha valore monetario, mentre una conversione di tipo TRANSAZIONE sì. Alcuni esempi sono le registrazioni alla mailing list (AZIONE) rispetto agli acquisti e-commerce (TRANSAZIONE).

  Se specifichi TRANSACTION, devi specificare anche il seguente campo:

  • revenueMicros: il valore monetario della conversione.

Campi facoltativi

• quantityMillis: il numero di elementi in questa conversione. Ad esempio, il numero di persone che si sono iscritte a una newsletter via email o la quantità totale di articoli venduti. Se non specifichi questo campo per le conversioni di tipo Azione, Search Ads 360 inserisce automaticamente un valore di 1000.
• currencyCode: la valuta delle entrate di una transazione. Per impostazione predefinita, si presume che le entrate siano espresse nella valuta dell'inserzionista. Se specifichi una valuta diversa, Search Ads 360 converte l'importo delle entrate specificato nella valuta dell'inserzionista. Scopri di più
  Utilizza il formato alfabetico ISO 4217 (3 caratteri) per specificare la valuta.
  Valido solo per le conversioni di tipo TRANSAZIONE.
• customMetric e customDimension: caricano dati aggiuntivi su una conversione, ad esempio il paese in cui viene spedito un articolo acquistato, gli ID prodotto o persino la durata di una chiamata. Scopri di più sul caricamento dei dati per le variabili Floodlight personalizzate.
• deviceType: specifica il tipo di dispositivo su cui è avvenuta la conversione. Consulta l'elenco dei valori accettati per questo campo.

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "criterionId": "43700003491981017", // Replace with your ID
    "conversionId": "customerTransaction73126",
    "conversionTimestamp": "1351196386000",
    "segmentationType": "FLOODLIGHT",
    "segmentationName": "Offline Purchase",
    "type": "TRANSACTION",
    "revenueMicros": "20000000", // 20 million revenueMicros is equivalent to $20 of revenue
    "currencyCode": "USD"
  }]
}

  /**
   * Creates a TRANSACTION conversion, attributes it to a keyword only, and adds it to a List<Conversion>.
   * The example in the preceding section contains the uploadConversions method,
   * which can submit the list as an insert() request.
   */
  private static List<Conversion> addTransactionConversionForKeyword(List<Conversion> conversions,
      Long criterionId, String conversionId, Long revenue, Long timeStamp) {

    Conversion conversion = new Conversion()
        .setCriterionId(criterionId)
        .setConversionId(conversionId)
        .setSegmentationType("FLOODLIGHT")
        .setSegmentationName("Test")
        .setType("TRANSACTION")
        .setRevenueMicros(revenue)
        .setCurrencyCode("USD")
        .setConversionTimestamp(BigInteger.valueOf(timeStamp));

    conversions.add(conversion);
    return conversions;
  }        

def insert_conversion(service):
  """Create and upload a TRANSACTION conversion that is attributed to a keyword only.

  Args:
    service: An authorized Doubleclicksearch service. See Set Up Your Application.
  """
  request = service.conversion().insert(
      body=
      {
          'conversion': [{
              'criterionId': '43700004289911004', // Replace with your ID
              'conversionId': 'test_1378710000000',
              'conversionTimestamp': '1378710000000',
              'segmentationType': 'FLOODLIGHT',
              'segmentationName': 'Test',
              'type': 'TRANSACTION',
              'revenueMicros': '20000000', // 20 million revenueMicros is equivalent to $20 of revenue
              'currencyCode': 'USD'
              }]
      }
  )

  pprint.pprint(request.execute())

Esempio

POST  https://www.googleapis.com/doubleclicksearch/v2/conversion
Authorization: Bearer your OAuth 2.0 access token
Content-type: application/json
{
 "kind": "doubleclicksearch#conversionList",
  "conversion" : [{
    "clickId" : "PP5K8iI6ul7Vw09JZZDEp", // Replace with a click ID from your site
    "conversionId" : "test_20130906_04",
    "conversionTimestamp" : "1378710000000",
    "segmentationType" : "FLOODLIGHT",
    "segmentationName" : "Test",
    "type": "TRANSACTION",
    "attributionModel": "External Attribution Model",
    "countMillis": "330",
    "revenueMicros": "33000000", // 33 million revenueMicros is equivalent to $33 of revenue
    "currencyCode": "USD"
  }]
}
          

errori di convalida della richiesta

Gli errori requestValidation indicano problemi con i dati nella richiesta di caricamento delle conversioni (ad es. la conversione è già stata caricata o non è stato trovato il valore clickId). In questo tipo di errore, i dettagli del messaggio contengono due elementi:

• Un codice esadecimale che identifica il tipo di errore. Puoi utilizzare il codice nei tuoi script per identificare gli errori.
• Una descrizione dell'errore di convalida.

Per ulteriori informazioni, consulta l'elenco di codici e descrizioni che Search Ads 360 può restituire per gli errori di caricamento delle conversioni.

Altri tipi di errori

Tutti gli altri tipi di errori (internalError, transactionFailed o lateStageRequestError) indicano che esiste un problema interno in Search Ads 360.

Rispondere a un errore

Se la richiesta non va a buon fine, prova a inviare di nuovo l'intera chiamata di richiesta in un secondo momento. Search Ads 360 segnalerà errori requestValidation per le conversioni già caricate, ma tenterà di caricare le conversioni rimanenti.

Se gli errori persistono dopo il nuovo invio, consulta la sezione sulla risoluzione dei problemi per informazioni su come procedere.