oEmbed di Instagram

Interroga l'endpoint oEmbed di Instagram per ottenere il codice HTML e i metadati di base di un post di Instagram in modo da incorporarlo in un altro sito web o in un'altra app. Funziona per i post con foto, video, reel e raccolte.

Utilizzi comuni

Rendering dei post nelle app di messaggistica.
Incorporamento dei post in siti web e blog.
Rendering dei post in un sistema di gestione dei contenuti.

Endpoint

Endpoint	Descrizione
`GET /instagram_oembed`	Consente di ottenere il codice HTML e i metadati di base per incorporare un post di Instagram.

Requisiti

Un account sviluppatore di Facebook
Un'app Facebook in modalità live
Un token d'accesso
Analisi dell'app per la funzione oEmbed Read

Limitazioni

L'endpoint oEmbed di Instagram deve essere utilizzato esclusivamente per incorporare i contenuti Instagram in siti web e app. Non è progettato per alcun altro scopo. È severamente vietato usare i metadati e i contenuti di pagine, post o video (o i relativi derivati) dall'endpoint per finalità diverse dal fornire una visualizzazione front-end di tale pagina, post o video. Questo divieto comprende l'utilizzo, la manipolazione, l'estrazione o la persistenza di metadati e contenuti, tra cui la derivazione di informazioni su pagine, post e video dai metadati per finalità di analisi.
Non funziona per i post su account Instagram privati, inattivi e soggetti a limitazioni legate all'età.
Non funziona per gli account con incorporamenti disabilitati.
Non funziona per le storie.
Non funziona per Shadow DOM.

Analisi dell'app

Per usare oEmbed, l'app deve essere sottoposta all'analisi dell'app per la funzione oEmbed Read.

Per il campo Fornisci un URL in cui testare oEmbed Read del modulo, usa l'endpoint oEmbed di Instagram per ottenere il codice HTML in modo da incorporare qualsiasi post pubblico sulla nostra Pagina Facebook o Pagina Instagram ufficiale (oppure per ottenere il codice HTML al fine di incorporare una delle due pagine). Aggiungi il codice HTML ottenuto nella pagina su cui visualizzare il contenuto oEmbed, quindi inserisci l'URL della pagina nel campo del modulo.

Dopo aver ottenuto l'approvazione per la funzione oEmbed Read, potrai incorporare pagine, post o video utilizzando i rispettivi URL.

Token d'accesso

L'endpoint oEmbed di Instagram richiede un token d'accesso dell'app (consigliato) o un token d'accesso del client.

Token d'accesso dell'app

Se la tua app si basa su un server di back-end, ti consigliamo di utilizzare un token d'accesso dell'app quando accedi all'endpoint oEmbed. I rate limit dipendono dal tipo di token incluso nella richiesta e i rate limit dei token dell'app consentono fino a 5 milioni di richieste al giorno.

Le istruzioni per la generazione di token d'accesso dell'app sono disponibili nella sezione Token dell'app della documentazione sui token d'accesso.

Tieni presente che i token d'accesso dell'app non devono in alcun caso essere usati lato client. Devono essere sempre protetti e memorizzati sul tuo server. Se l'app richiede l'utilizzo di un token lato client, utilizza un token d'accesso del client.

Token d'accesso del client

Se l'app deve accedere all'endpoint oEmbed da un agente utente, come un dispositivo mobile o un browser web, dovrà utilizzare un token d'accesso del client e sarà soggetta ai relativi rate limit.

Per ottenere un token d'accesso del client, accedi alla Dashboard gestione app e vai su Impostazioni > Avanzate > Sicurezza > Token client.

A differenza dei token d'accesso dell'app, quelli del client non possono essere utilizzati da soli nelle richieste dell'endpoint oEmbed, ma è necessario combinarli con l'ID app. Per farlo, aggiungi il token alla fine dell'ID app separandolo con una barra verticale (|).

{app-id}|{client-token}

Ad esempio:

access_token=1234|5678

Rate limiting

I rate limit dipendono dal tipo di token d'accesso incluso dall'app in ogni richiesta.

Rate limit dei token dell'app

Le app che si basano sui token d'accesso dell'app possono generare fino a 5 milioni di richieste in 24 ore.

Rate limit dei token client

I rate limit dei token client sono decisamente inferiori rispetto a quelli dei token dell'app. Non indichiamo un limite effettivo perché varia a seconda dell'attività dell'app. Ad ogni modo, puoi tranquillamente presumere che la tua app non raggiungerà il suo limite a meno che non mostri comportamenti tipici di un bot, come l'invio in batch di migliaia di richieste per agente o utente dell'app.

Richiesta di un HTML di incorporamento

Per ottenere il codice HTML in modo da incorporare un post di Instagram, invia una richiesta a:

GET /instagram_oembed?url={url}&access_token={access-token}

Sostituisci {url} con l'URL del post di Instagram che desideri interrogare e {access-token} con il tuo token d'accesso dell'app o del client (oppure passalo a noi in un'intestazione HTTP). Se utilizzi un token d'accesso del client, ricorda che devi combinarlo con l'ID app utilizzando una barra verticale, altrimenti la richiesta non andrà a buon fine.

Se l'operazione va a buon fine, l'API risponde con un oggetto JSON contenente il codice HTML per incorporare il post e i dati aggiuntivi. Il codice HTML di incorporamento verrà assegnato alla proprietà html.

Consulta il riferimento oEmbed di Instagram per una lista di parametri della stringa di query che puoi includere per perfezionare la richiesta. Puoi anche includere il parametro della stringa di query fields per specificare i campi che desideri ottenere. Qualora venisse omesso, verranno inclusi nella risposta tutti i campi predefiniti.

Esempio di richiesta

curl -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https://www.instagram.com/p/fA9uwTtkSN/&access_token=IGQVJ..."

Esempio di risposta

Alcuni valori sono stati troncati con i puntini di sospensione (...) per migliorare la leggibilità.

{
  "version": "1.0",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/",
  "type": "rich",
  "width": 658,
  "html": "<blockquote class=\"instagram-media\" data-instgrm-ca...",
  "thumbnail_width": 640,
  "thumbnail_height": 640
}

Formati URL

Il parametro della stringa della query url accetta i seguenti formati URL:

https://www.instagram.com/p/{media-shortcode}/
https://www.instagram.com/tv/{media-shortcode}/https://www.instagram.com/{username}/guide/{slug}/{guide_id}

Embed JS

L'HTML di incorporamento contiene un riferimento alla libreria JavaScript embed.js di Instagram. Una volta caricata, la libreria scansiona la Pagina in cerca dell'HTML del post e genera un post interamente renderizzato. Se desideri caricare la libreria separatamente, includi il parametro della stringa di query omitscript=true nella tua richiesta. Per inizializzare manualmente l'HTML di incorporamento, chiama la funzione instgrm.Embeds.process() dopo il caricamento della libreria.

Dimensioni del post

Il post incorporato è responsivo e si adatterà alle dimensioni del suo contenitore. Questo significa che l'altezza varierà a seconda della larghezza del contenitore e della lunghezza della didascalia. Puoi impostare la larghezza massima includendo il parametro della stringa di query maxwidth nella tua richiesta.

Come ottenere le miniature

Quando possibile, ti consigliamo di visualizzare interamente il codice HTML di incorporamento del post. Se non riesci a farlo, puoi ottenere un URL della miniatura del post da visualizzare al posto del codice. Tuttavia, se decidi di procedere in questo modo, devi indicare un'attribuzione chiara accanto all'immagine, inclusa quella per l'autore originale e per Instagram, oltre a un link al post di Instagram che stai interrogando.

Per ottenere un URL della miniatura di un post e le informazioni sulle attribuzioni, invia una richiesta a:

GET /instagram_oembed
  ?url={url}
  &maxwidth={maxwidth}
  &fields=thumbnail_url,author_name,provider_name,provider_url
  &access_token={access-token}

Sostituisci {url} con l'URL del post di Instagram che desideri interrogare, {maxwidth} con le dimensioni massime della miniatura che desideri visualizzare e {access-token} con il tuo token d'accesso dell'app o del client.

Esempio di richiesta

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN&maxwidth=320&fields=thumbnail_url%2Cauthor_name%2Cprovider_name%2Cprovider_url&access_token=96481..."

Esempio di risposta

Alcuni valori sono stati troncati con i puntini di sospensione (...) per una maggiore leggibilità.

{
  "thumbnail_url": "https://scontent.cdninstagram.com/v/t51.288...",
  "author_name": "diegoquinteiro",
  "provider_name": "Instagram",
  "provider_url": "https://www.instagram.com/"
}

Passaggio dei token d'accesso in un'intestazione

Se non desideri includere il token d'accesso nella stringa di query della richiesta, puoi passarcelo tramite un'intestazione HTTP Authorization.

Authorization: Bearer {access-token}

Ad esempio:

curl -i -X GET \
  "https://graph.facebook.com/v19.0/instagram_oembed?url=https%3A%2F%2Fwww.instagram.com%2Fp%2FfA9uwTtkSN" \
  --header "Authorization: Bearer 96481..."