App sviluppatore

​

Panoramica

Se disponi di App esistenti, puoi visualizzarle, modificarle o eliminarle tramite la pagina App del developer portal.

L’accesso alla X API e alla X Ads API richiede un set di credenziali di autenticazione, note anche come chiavi e token, da includere in ogni richiesta. Queste credenziali possono assumere forme diverse a seconda del tipo di autenticazione richiesto dallo specifico endpoint che stai utilizzando.

Di seguito sono riportate le diverse credenziali che puoi generare nella tua App e come utilizzarle:

• API Key and Secret: In sostanza, il nome utente e la password della tua App. Le utilizzerai per autenticare le richieste che richiedono il Contesto utente OAuth 1.0a o per generare altri token come gli Access Token utente o l’App Access Token.

• Access Token and Secret: In generale, gli Access Token rappresentano l’utente per conto del quale stai effettuando la richiesta. Quelli che puoi generare tramite il developer portal rappresentano l’utente proprietario dell’App. Li utilizzerai per autenticare le richieste che richiedono il Contesto utente OAuth 1.0a. Se desideri effettuare richieste per conto di un altro utente, dovrai utilizzare il flusso OAuth a 3 attori affinché ti autorizzi.

• Client ID and Client Secret: Queste credenziali sono utilizzate per ottenere un Access Token utente con autenticazione OAuth 2.0. Analogamente a OAuth 1.0a, gli Access Token utente vengono utilizzati per autenticare richieste che forniscono informazioni private dell’account utente o eseguono azioni per conto di un altro account, ma con ambiti granulari per un maggiore controllo sul tipo di accesso che l’applicazione client ha sull’utente.

• App only Access Token: Utilizzerai questo token quando effettui richieste a endpoint che restituiscono informazioni pubblicamente disponibili su X.

Oltre a generare le chiavi e i token necessari per effettuare richieste alla X API, potrai anche impostare le autorizzazioni di accesso, documentare il caso d’uso o lo scopo dell’App, definire un callback URL e modificare altre impostazioni relative all’ambiente di sviluppo della tua App all’interno del management dashboard.

​

App e Project

Puoi utilizzare le App e i Project per organizzare il tuo lavoro con la X Developer Platform in base ai casi d’uso. Ogni Project può includere una App con il piano Free X API, fino a due App con il piano Basic e fino a tre App con il piano Pro.

Se desideri accedere ai nuovi endpoint di X API v2, dovrai utilizzare chiavi e token di una App associata a un Project.

Se hai App create prima del lancio dei Project, saranno visibili nella sezione intitolata “Standalone Apps”. Le Standalone Apps sono App al di fuori della struttura del Project. Se associ una Standalone App a un Project, potrà quindi inviare richieste agli endpoint v2.

​

Dashboard del developer portal

Puoi accedere alla dashboard per gestire le App associate al tuo account. Per ulteriori informazioni, visita la nostra pagina di documentazione sul developer portal. La dashboard consente agli sviluppatori di svolgere rapidamente le seguenti attività:

• Visualizzare le App Standalone esistenti e il relativo App ID.
• Creare un nuovo Project, un’App o un’App standalone.
• Eliminare un Project o un’App non utilizzati.
• Rivedere o aggiornare le impostazioni di una specifica App, inclusi nome, descrizione, sito web, URL di callback e permissions.
• Rigenerare le credenziali specifiche dell’App, come API Key & Secret, App Access Token e gli Access Token utente del proprietario dell’App.

​

Registrazione per l’accesso

Se disponi di X App esistenti, puoi visualizzare e modificare le tue App tramite l’App dashboard di X se hai effettuato l’accesso al tuo account X su developer.x.com. Tieni presente che non è necessario registrare un account per gestire qualsiasi App creata in precedenza su developer.x.com.

Se devi creare una nuova X App, devi prima registrare un account sviluppatore. Se fai parte di un team account, ti deve essere assegnato il ruolo di amministratore per creare una nuova App.

​

Etichetta “Account automatizzato” per i bot

Puoi aggiungere l’etichetta “Account automatizzato” ai tuoi account bot per informare gli utenti su X che il tuo bot è un account automatizzato. Questi bot eseguono azioni programmate tramite la X API. Quando aggiungi l’etichetta “Account automatizzato” al tuo bot, rafforzi la fiducia del tuo pubblico, legittimi il tuo account e ti distingui dai bot di spam. Questo aiuta le persone su X a comprendere meglio lo scopo del tuo account quando interagiscono con il tuo bot.

Per associare un’etichetta al tuo account bot, segui questi passaggi:

1. Vai alle impostazioni del tuo account
2. Seleziona “Il tuo account”
3. Seleziona “Automazione”
4. Seleziona “Gestione account”
5. Quindi seleziona l’account X che gestisce il tuo account bot
6. Inserisci la tua password per accedere
7. Infine, dovresti vedere la conferma che l’etichetta è stata applicata al tuo account.

---

​

Gestione delle App

​

Introduzione

La dashboard X App consente agli sviluppatori di effettuare rapidamente le seguenti operazioni:

• Visualizzare le App e i Project esistenti e il relativo App ID associato.
• Creare un nuovo Project o un’App standalone.
• Eliminare un Project, un’App o un’App standalone.
• Aprire le impostazioni di una specifica App cliccando sull’App. Nelle impostazioni puoi vedere i dettagli dell’App, le chiavi e i token, e le autorizzazioni.
• Aggiornare le impostazioni di autenticazione utente della tua App per usare OAuth 1.0a o OAuth 2.0.

Nota:

Tutte le chiavi e i token dell’App non sono più visualizzabili nel developer portal e devono essere salvati in modo sicuro una volta generati. Consigliamo di utilizzare un gestore di password per archiviare le tue chiavi e i tuoi token.

Puoi mostrare un suggerimento per l’API Key per aiutarti a collegare le tue credenziali all’App corrispondente.

​

Impostazioni App

​

Dettagli dell’App

Qui puoi modificare l’icona dell’App, il nome dell’App, la descrizione dell’App, l’URL del tuo sito web, le callback URLs/redirect URIs, l’URL dei termini di servizio, l’URL dell’informativa sulla privacy, il nome dell’organizzazione, l’URL dell’organizzazione e lo scopo o caso d’uso dell’App.

OAuth 2.0 e OAuth 1.0a sono metodi di autenticazione che consentono agli utenti di accedere alla tua App con X. Consentono anche alla tua App di effettuare richieste specifiche per conto degli utenti autenticati. Puoi attivare uno o entrambi i metodi per la tua App.

È importante mantenere queste informazioni aggiornate. Il nome della tua App e l’URL del sito web verranno mostrati come fonte all’interno dei metadata per qualsiasi Tweet creato programmaticamente dalla tua applicazione. Se modifichi il caso d’uso di una X App, assicurati di aggiornarlo in queste impostazioni per garantire la conformità ai Developer Terms.

Se la tua applicazione ha un tag con la dicitura “suspended”, è perché la tua App viola uno o più dei developer terms di X, ad esempio le nostre automation rules. Il team di policy della piattaforma per sviluppatori comunicherà con gli sviluppatori tramite l’indirizzo email configurato sull’account X del proprietario dell’App; per verificare questo indirizzo email consulta le impostazioni del tuo account X. Le email di notifica relative alle sospensioni saranno inviate a questo indirizzo con un titolo simile a “Application suspension notice” e conterranno informazioni specifiche su cosa fare in seguito. Per collaborare con il team di X nella gestione delle sospensioni, controlla la tua email per istruzioni specifiche oppure utilizza il nostro platform help form.

​

Chiavi e token

All’interno di un’App in un Project o tramite un’App autonoma puoi visualizzare, rigenerare o revocare i seguenti token:

• API Key (Consumer Key) e API Secret (Consumer Secret)
• App Access Token
• User Access Token e Access Token Secret - L’Access Token e l’Access Token Secret disponibili nel developer portal si riferiscono all’utente proprietario dell’App.

Nota - Se desideri effettuare richieste per conto di un utente diverso (cioè non l’utente proprietario dell’App), devi utilizzare il flusso OAuth 1.0a a 3 attori oppure il flusso OAuth 2.0 Authorization Code con PKCE per generare un set di Access Token utente. Userai poi questi token specifici dell’utente nella richiesta all’API.

​

Impostazioni di autenticazione utente

Puoi configurare l’autenticazione della tua App per usare OAuth 1.0a oppure OAuth 2.0. OAuth 2.0 può essere utilizzato solo con la X API v2. OAuth 2.0 consente di selezionare ambiti granulari che forniscono autorizzazioni specifiche per conto di un utente. OAuth 1.0a può essere utilizzato con la X API v1.1 e v2 e adotta un modello di autorizzazione più ampio con ambiti meno granulari.

​

Autorizzazioni applicazione-utente OAuth 1.0a

Se sei il proprietario dell’App, puoi modificare le autorizzazioni dell’App (solo lettura; lettura e scrittura; oppure lettura, scrittura e messaggi diretti). Questo determina a quali risorse ed eventi puoi accedere tramite la X API (nota: alcune risorse richiedono ulteriori autorizzazioni direttamente da X).

Puoi anche attivare o disattivare, in questa pagina, la possibilità per le tue App di richiedere gli indirizzi email degli utenti (sono necessari un URL dei Termini di servizio e un URL dell’Informativa sulla privacy nella pagina “Dettagli App”).

​

Tipo di App OAuth 2.0

Se selezioni OAuth 2.0 come metodo di autenticazione utente, dovrai scegliere il tipo di App che stai creando. Le opzioni sono Native App, Single Page App, Web App, Automated App o bot. Le Native App e le Single Page App sono client pubblici, mentre le Web App e le Automated App o i bot sono client riservati.

I client riservati si autenticano in modo sicuro con il server di autorizzazione e mantengono al sicuro il tuo client secret. I client pubblici sono applicazioni che solitamente vengono eseguite in un browser o su un dispositivo mobile e non possono utilizzare i tuoi client secret. Se selezioni un tipo di App che è un client riservato, ti verrà fornito un client secret.

---

​

Autorizzazioni dell’App

​

Autorizzazioni dell’App OAuth 1.0a

Le autorizzazioni dell’App descrivono il livello di accesso per l’autenticazione utente‑applicazione OAuth 1.0a. Le autorizzazioni dell’App sono configurate per ciascuna applicazione nelle impostazioni della tua X App.

Sono disponibili tre livelli di autorizzazione:

1. Sola lettura
2. Lettura e scrittura
3. Lettura, scrittura e accesso ai Messaggi diretti

Esiste un’autorizzazione aggiuntiva per richiedere la visualizzazione dell’indirizzo email di un utente: può essere combinata con uno qualsiasi dei tre livelli elencati sopra.

Se un livello di autorizzazione viene modificato, eventuali token utente già emessi per quella X App devono essere invalidati e gli utenti devono ri-autorizzare l’App affinché il token erediti le autorizzazioni aggiornate.

È buona prassi richiedere solo il livello minimo di accesso ai dati dell’account utente necessario all’applicazione o al servizio.

​

Sola lettura

Questo livello di autorizzazione consente l’accesso in lettura alle risorse di X, tra cui (ad esempio) i Tweet di un utente, la home timeline e le informazioni del profilo. Non consente di leggere i Messaggi diretti di un utente e non permette di aggiornare alcun elemento o oggetto.

​

Lettura e scrittura

Questo livello di autorizzazione consente l’accesso in lettura e scrittura alle risorse di X. Oltre a consentire l’accesso in lettura, consente anche di pubblicare Tweet, seguire gli utenti o aggiornare elementi delle informazioni del profilo di un utente. Consente inoltre di nascondere le risposte per conto dell’utente che effettua l’autenticazione. Questo livello di autorizzazione non consente alcun accesso ai Messaggi diretti (inclusi lettura, scrittura o delete).

​

Leggere, scrivere e accedere ai Messaggi diretti

Questo livello di autorizzazione include l’accesso a tutto quanto sopra e aggiunge la possibilità di leggere, scrivere ed eliminare Messaggi diretti per conto di un utente.

• POST /2/dm_conversations/:dm_conversation_id/messages
• POST /2/dm_conversations/
• POST /2/dm_conversations/with/:participant_id/messages
• GET /2/dm_conversations/with/:user_id/dm_events
• GET /2/dm_conversations/:dm_conversation_id/dm_events
• GET /2/dm_events

​

Determinazione delle autorizzazioni

Tutte le richieste API autenticate restituiscono l’intestazione x-access-level nella risposta HTTP. Il valore dell’intestazione indica il livello di autorizzazione attualmente in uso. I possibili valori sono read, read-write e read-write-directmessages.

---

​

URL di callback

I metodi di autenticazione Contesto utente OAuth 1.0a e OAuth 2.0 Authorization Code con PKCE consentono agli sviluppatori di effettuare richieste per conto di diversi utenti di X che hanno seguito uno specifico flusso di accesso. Attualmente, ci sono due flussi che puoi utilizzare per consentire agli utenti di autorizzare la tua applicazione:

• Flusso del codice di autorizzazione OAuth 2.0 con PKCE
• Flusso OAuth 1.0a a 3 attori (e, separatamente, il flusso Accedi con X)

Man mano che gli utenti seguono questi flussi, hanno bisogno di una pagina web o di una destinazione a cui essere inviati dopo aver effettuato correttamente l’accesso e aver concesso l’autorizzazione all’App dello sviluppatore. Questa pagina web o destinazione successiva è chiamata URL di callback.

Quando configurano questi flussi per i potenziali utenti, gli sviluppatori devono includere un URL di callback nelle richieste agli endpoint di autenticazione che costituiscono i flussi menzionati in precedenza. Ad esempio, gli sviluppatori che utilizzano il Contesto utente OAuth 1.0a devono passare il parametro callback_url quando effettuano una richiesta all’endpoint GET oauth/request_token. Analogamente, gli sviluppatori che utilizzano OAuth 2.0 Authorization Code con PKCE devono passare il parametro redirect_uri con la loro richiesta all’endpoint GET oauth2/authorize.

Oltre a utilizzare questi parametri, lo sviluppatore deve anche assicurarsi che l’URL di callback sia stato aggiunto alla allowlist degli URL di callback della propria App, che si trova nella pagina delle impostazioni dell’App del developer portal.

Se la configurazione è corretta, gli sviluppatori verranno reindirizzati all’URL di callback dopo aver effettuato correttamente l’accesso a X come parte di questi flussi.

​

Cose da tenere a mente

Quando configuri gli URL di callback, ci sono alcune cose da considerare:

Codifica HTTP dei parametri di query

Poiché stai passando l’URL di callback come parametro di query tramite callback_url o redirect_uri, assicurati di codificare l’URL in HTTP.

Limiti degli URL di callback

Nel dashboard delle X App è previsto un limite rigido di 10 URL di callback. L’URL di callback deve sempre corrispondere esattamente tra l’URL autorizzato che aggiungi nel dashboard delle App e il parametro che inserisci nel flusso di autorizzazione.

Se desideri includere dati specifici della richiesta nell’URL di callback, puoi utilizzare il parametro state per memorizzare i dati che saranno inclusi dopo il reindirizzamento dell’utente. Puoi codificare i dati direttamente nel parametro state oppure usare il parametro come id di sessione per memorizzare lo stato sul server.

Non utilizzare localhost come URL di callback Invece di usare localhost, utilizza un host personalizzato in locale oppure http(s)://127.0.0.1

URL con protocollo personalizzato Se desideri sfruttare il deep linking su mobile, puoi utilizzare URL con protocollo personalizzato con una parte di percorso e dominio, come twitter://callback/path. Tuttavia, esiste un elenco di protocolli non consentiti che dovrai evitare. Puoi consultare l’elenco dei protocolli non consentiti di seguito.

Protocolli non consentiti

vbscript	ldap
javascript	mailto
vbs	mmst
data	mmsu
mocha	msbd
keyword	rtsp
livescript	mso-offdap
ftp	snews
file	news
gopher	nntp
acrobat	outlook
callto	stssync
daap	rlogin
itpc	telnet
itms	tn3270
firefoxurl	shell
hcp	sip

​

Esempio di errore

Se utilizzi un URL di callback che non è stato aggiunto correttamente alle impostazioni della tua App nel developer portal, riceverai il seguente messaggio di errore:

OAuth 1.0a

HTTP 403 - Forbidden

{
  "errors": [
    {
      "code":415,"message":"URL di callback non approvato per questa App client. Gli URL di callback approvati possono essere modificati nelle impostazioni della tua App."
    }
  ]
}

Oppure

<?xml version="1.0" encoding="UTF-8"?>
<hash>
<error>URL di callback non approvato per questa applicazione client. Gli URL di callback approvati possono essere modificati nelle impostazioni dell'applicazione</error>
<request>/oauth/request_token</request>
</hash>

OAuth 2.0

HTTP 400

{
  "error": "invalid_request",
  "error_description": "Il valore passato per l'URI di reindirizzamento non corrisponde all'URI del codice di autorizzazione."
}

Risoluzione dei problemi

Se ricevi un errore, verifica che l’URL di callback utilizzato nelle richieste di autenticazione sia codificato in HTTP e che corrisponda a un URL di callback aggiunto alla allowlist dell’App le cui chiavi e token stai utilizzando nella richiesta.

---