API Control Plane del gateway dell'API Conversions per più account

Integrazione partner

Panoramica

L'API Control Plance del gateway dell'API Conversions per più account è un insieme di API GraphQL esposte dall'istanza del gateway. Permette agli sviluppatori di gestire programmaticamente account, origini di dati e altre configurazioni di un'istanza del gateway. I partner possono integrare l'API nell'interfaccia utente rivolta agli inserzionisti e offrire a questi ultimi un flusso di registrazione e gestione ottimale.

Casi d'uso potenziali:

Gli inserzionisti si registrano sul gateway usando l'interfaccia utente del partner ed eseguono azioni di follow-up tramite le impostazioni di amministratore del gateway. Ciò richiede un'integrazione parziale dell'API Control Plane.
Gli inserzionisti eseguono tutte le azioni sull'interfaccia utente del partner, incluse la registrazione al gateway e le azioni di follow-up. Può essere un buon caso d'uso per i partner che non vogliono esporre l'interfaccia utente del gateway, ma vogliono comunque fornire il gateway come servizio per gli inserzionisti. Ciò richiede la piena integrazione dell'API Control Plane.

Consulta la sezione sottostante per maggiori dettagli sulla procedura di integrazione.

API Control Plane del gateway dell'API Conversions per più account o gateway sono usati in modo intercambiabile in questo documento.

Guida all'integrazione

A seconda del caso d'uso, ci possono essere due percorsi di integrazione (come mostrato nel diagramma sottostante):

Integrazione parziale dell'API Control Plane. Questa procedura non richiede l'autenticazione degli inserzionisti.
Integrazione completa con l'API Control Plane. Questa procedura richiede l'autenticazione degli inserzionisti usando l'estensione Meta Business (MBE) o la generazione manuale di token.

Prerequisiti

Per entrambi i percorsi di integrazione, il partner deve prima completare i passaggi seguenti:

Passaggio 1: effettuare la registrazione come host dell'istanza del gateway

Passaggio 2: generare il nome dell'account API e chiave segreta dell'API

Vai a:

https://<Conversions API Gateway Endpoint>/hub/

Vai alla tab Impostazioni host, seleziona la pagina Gestisci account API e clicca sul pulsante dell'account Aggiungi API.

Inserisci nuovamente la tua password. Clicca su Continua.

Inserisci il nome dell'account API. Clicca su Continua.

Il nome dell'account può contenere solo lettere e numeri e non può contenere spazi. La lunghezza massima è 20.

Copia e salva la chiave segreta generata. Non potrai vederla di nuovo.

Per rimuovere un account API, clicca su Elimina account API. L'azione non è reversibile e può potenzialmente causare interruzioni alle app o ai servizi degli inserzionisti che utilizzano l'API.

Integrazione parziale

Un caso d'uso basato sull'integrazione parziale:

L'inserzionista opta per il servizio del gateway utilizzando l'interfaccia utente del partner.
Il partner genera un link di invito che può essere usato dall'inserzionista per configurare una password e completare la creazione di un account del gateway.
L'inserzionista usa le funzionalità sull'interfaccia utente del gateway per eseguire azioni come la gestione delle origini di dati, degli utenti dell'account, dei domini e dei routing.
Il partner recupera l'uso dell'account dell'inserzionista e fattura di conseguenza.

Un flusso utente di alto livello può essere simile al seguente:

Per ottenere quanto riportato sopra, il partner può integrare un sottoinsieme di API Control Plane, tra cui:

Ottenere il token d'accesso dell'API
Creare un account per gli inserzionisti
Ottenere l'uso dell'account, ad esempio, per scopi di fatturazione

Integrazione completa

Un caso d'uso basato sull'integrazione completa:

L'inserzionista opta per il servizio del gateway utilizzando l'interfaccia utente del partner.
Il partner registra l'account del gateway dell'inserzionista e riceve l'autorizzazione a gestire l'account; l'inserzionista autorizza il partner che utilizza l'estensione Meta Business (MBE) o la generazione di token manuale.
L'inserzionista può eseguire la gestione delle origini dei dati, nonché la gestione di utenti dell'account, domini e routing nell'interfaccia utente del partner.
Il partner recupera l'uso dell'account dell'inserzionista e fattura di conseguenza.

Un flusso utente di alto livello può essere simile al seguente:

Per questo percorso di integrazione, i partner devono richiedere l'autorizzazione e ottenere i token d'accesso dell'utente di sistema tramite autenticazione per inviare eventi per conto degli inserzionisti.

Autenticazione

I partner hanno le due opzioni di autenticazione seguenti per i pixel di Meta non gestiti da loro:

Opzione 1 - Estensione Meta Business (MBE)

Prima di iniziare, devi eseguire le operazioni seguenti:

Completare tutti i requisiti per implementare MBE
Contattare il tuo rappresentante di Meta per aggiungere la tua app alla lista di elementi consentiti per un'autorizzazione privata: open_bridge_configuration_management

MBE fornisce un endpoint per recuperare i token d'accesso degli utenti di sistema creati nel Business Manager dell'inserzionista. I partner possono fare riferimento al passaggio 4 della guida all'integrazione MBE. Assicurati di:

impostare il valore del parametro del canale nell'oggetto di configurazione setup come CONVERSIONS_API_GATEWAY_ADVERTISER;
essere in grado di ricevere la risposta webhook al completamento della registrazione;
usare il token d'accesso restituito tramite MBE e convertirlo in un token d'accesso dell'utente di sistema facendo un'ulteriore chiamata API;
salvare una copia di external_business_id, pixel_id, business_id e token d'accesso dell'utente di sistema nel tuo sistema.

Opzione 2 - Token d'accesso dell'utente di sistema client

Con questa opzione, i partner possono fare in modo che gli inserzionisti eseguano le azioni seguenti:

Creare manualmente un token d'accesso dell'utente di sistema tramite l'API Conversions all'interno di Impostazioni in Gestione eventi
Condividere pixel_id, business_id e il token d'accesso dell'utente di sistema con il partner e salvarne una copia

Integrazione

I partner possono integrare l'insieme completo di API Control Plane. Ulteriori dettagli sono trattati nel riferimento all'API.

Parità API e interfaccia utente

Viene applicata la parità tra API e interfaccia utente esponendo gli stessi endpoint API usati nell'interfaccia utente del gateway. Tuttavia, qualsiasi endpoint API non contemplato nel riferimento all'API è soggetto a cambiamenti nello sviluppo futuro. Per limitare al minimo eventuali conseguenze impreviste, gli endpoint API non coperti restituiscono il codice di errore: 418. Puoi ancora usare l'API, ma a tuo rischio e pericolo.