Accesso agli account pubblicitari

​

Account utente vs account pubblicitari

Esistono due diversi tipi di account coinvolti nell’utilizzo della X Ads API: account pubblicitari e account utente X. In tutta la documentazione della X Ads API, il termine “account” di solito si riferisce all’account pubblicitario.

• Gli account pubblicitari sono registrati su business.x.com e identificati nell’API tramite account_id. Sono collegati direttamente alle fonti di finanziamento e utilizzano i contenuti di uno o più account utente X come “promotable users”. Ogni account pubblicitario può concedere l’autorizzazione a uno o più account utente X. L’account pubblicitario, o “account corrente”, è rappresentato nella quasi totalità degli URL eseguiti come parametro in linea :account_id.
• Gli account utente X (ad esempio @AdsAPI) sono identificati da user_id nella X Ads API. Uno o più di questi account possono essere associati a un account pubblicitario. L’account utente X autenticato che effettua le richieste all’API è indicato come “current user”. Un elenco degli account pubblicitari a cui l’utente corrente ha accesso è disponibile con GET accounts. I “promotable users” sono handle X che possono essere promossi da uno specifico account pubblicitario. Per ulteriori dettagli, consulta Obtaining Ads Account Access.

​

Metodi per l’accesso all’account pubblicitario

Esistono due metodi per inviare richieste alla X Ads API per l’account di un inserzionista:

1. Inviare richieste per conto di un inserzionista (consigliato)
2. Inviare richieste utilizzando il tuo account a cui è stato concesso l’accesso all’account di un inserzionista, ad esempio un’agenzia che gestisce più account.

Questo documento offre una breve panoramica delle differenze tra queste opzioni e va utilizzato insieme ad altre nostre risorse, come le FAQ sull’accesso multi‑utente.

Come descritto in Autorizzare una richiesta, tutte le richieste alla X Ads API richiedono intestazioni di autorizzazione che utilizzino OAuth 1.0a con un access token ottenuto tramite il flusso OAuth a 3 passaggi OAuth. L’App dovrà implementare un flusso OAuth basato sul web per ottenere access token. Gli sviluppatori della X Ads API non devono mai chiedere agli inserzionisti di X di condividere le proprie credenziali di accesso.

Per impostazione predefinita, ogni X developer application contiene un access token statico che può essere utilizzato per inviare richieste alla X Ads API per l’account proprietario dell’applicazione. Queste credenziali sono ideali per casi d’uso a singolo account, senza richiedere un flusso OAuth a 3 passaggi o basato su PIN. Se non stai accedendo a un altro X Ads Account, utilizza queste credenziali single‑user invece dei passaggi seguenti.

​

Livelli di accesso

​

Autorizzazioni a livello di App

Ogni utente avrà un livello di accesso in base a quanto richiesto nella domanda di accesso alla X Ads API:

• Solo conversioni: l’utente ha accesso agli endpoint di Mobile e Web Conversion con accesso read & write.
• Accesso standard: l’utente ha accesso agli endpoint di Analytics, Campaign Management, Creatives, Custom Audiences e Conversion con accesso read & write.

Nota: Gli sviluppatori della X Ads API che hanno richiesto l’accesso prima di luglio 2023 potrebbero avere livelli di accesso e autorizzazioni diversi e potrebbero essere limitati a cinque token OAuth. Consulta la nostra guida su increasing access per ottenere l’accesso a endpoint aggiuntivi o rimuovere i limiti sui token per le applicazioni esistenti.

​

Autorizzazioni a livello di Ad Account

Ogni utente che ha accesso a un Ads Account dispone di una specifica autorizzazione a livello di account: Account administrator, Ad manager, Campaign analyst, Organic analyst e Creative Manager; consulta business.x.com per la documentazione più recente sulle autorizzazioni a livello di account. Le applicazioni devono recuperare le autorizzazioni dell’utente attualmente autenticato tramite l’endpoint API Authenticated User Access per determinare quali endpoint API e funzionalità Ads sono accessibili.

Nota: Qualsiasi token utente utilizzato con la Conversion API deve appartenere a utenti con autorizzazioni a livello di account Account administrator o Ad manager.                                                                                                                                              

​

Metodi per ottenere gli access token

​

1. Ottenere l’access token (User) di un inserzionista

Esistono due metodi per ottenere l’access token di un inserzionista. Il metodo più comune è tramite un flusso OAuth a 3 vie direttamente dalla tua interfaccia web. Le applicazioni che non dispongono di un’interfaccia pubblicamente accessibile agli inserzionisti possono implementare un processo OAuth basato su PIN. Dopo che l’utente ha completato il flusso a 3 vie, la tua applicazione disporrà delle credenziali per effettuare richieste per il suo account Ads tramite l’API.

Ottenere le credenziali utente tramite il flusso OAuth è il metodo che consigliamo vivamente alla maggior parte degli sviluppatori della X Ads API per ottenere l’accesso a un account inserzionista. Consente di chiamare l’API per conto di un utente ed eseguire azioni come tale utente. Questi token non scadono, ma possono essere revocati dall’utente in qualsiasi momento.

​

2. Ottieni il tuo access token (Developer)

Questa opzione richiede che l’inserzionista conceda al tuo @username (o ai tuoi @usernames) l’accesso al proprio account X Ads tramite la UI di X su business.x.com. Gli access token ottenuti tramite il flusso OAuth a 3 vie per il tuo account potranno accedere all’account X Ads dell’inserzionista.

Questo ti consente di chiamare l’API utilizzando i token OAuth del tuo @username invece dei token OAuth dell’inserzionista. L’aspetto fondamentale di questa opzione è che puoi creare Post “Promoted-Only” solo se al tuo @username è stato concesso il permesso di delega/composer dei Post.

Per ottenere l’accesso alla creazione di Post “Promoted-Only” per conto dell’utente promuovibile FULL sull’account, devi anche ottenere il permesso di creare Post in questo flusso. Ciò abiliterà l’accesso tramite il permesso TWEET_COMPOSER sull’endpoint GET accounts/:account_id/authenticated_user_access.

​

Differenze tra questi metodi

	OAuth Token Inserzionista (Utente)	OAuth Token (Sviluppatore)  (@username aggiunto per distinguere l’account)
Accesso all’account Ads	✔	✔
Creazione di Post per conto dell’utente	✔	✔*
Gestione delle campagne	✔	✔
Accesso ad Analytics	✔	✔
Creazione di Card per conto dell’utente	✔	✔
Possibilità per lo sviluppatore di accedere tramite l’UI di X Ads		✔
Limiti di velocità	Distinti per Inserzionista	Distinti per Account inserzionista

Nota: Vedi la sezione Ottieni il tuo access token (Sviluppatore) sopra per i dettagli.

​

Esempio di caso d’uso

​

Access Token dell’inserzionista tramite flusso web OAuth a 3 passaggi

Il flusso standard è web-based e utilizza il flusso OAuth di autorizzazione a 3 passaggi. Le schermate riportate qui fanno parte di un esempio di cui puoi consultare il codice sorgente su https://github.com/xdevplatform/twauth-web.

A un certo punto dell’applicazione, dovrai reindirizzare verso X per autorizzare la tua applicazione

Quando reindirizzi verso X con il request token, all’utente verrà richiesto di autorizzare la tua applicazione

Dopo l’autorizzazione, l’utente verrà reindirizzato alla callback URL fornita quando hai generato il request token. Utilizzerai questi dati per ottenere l’Access Token permanente per questo utente e archiviarlo localmente.