oEmbed di Facebook

Gli endpoint oEmbed di Facebook ti consentono di incorporare HTML e metadati di base per Pagine, post e video per visualizzarli in un altro sito web o in un'altra app.

Utilizzi comuni

• Visualizzazione di Pagine, post e video di Facebook nelle app di messaggistica
• Incorporamento di Pagine, post e video di Facebook in siti web e blog
• Visualizzazione di Pagine, post e video di Facebook in un sistema di gestione dei contenuti

Endpoint

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

Gli endpoint oEmbed di Facebook sono destinati esclusivamente ad essere utilizzati per incorporare contenuti di Facebook in siti web e app. Non sono progettati per alcun altro scopo. L'utilizzo di metadati e contenuti di Pagine, post o video (o di quanto ne deriva) dagli endpoint per qualsiasi scopo diverso dal fornire una visualizzazione front-end di tale Pagina, post o video è severamente proibito. 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.

Analisi dell'app

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

Per il campo del modulo Fornisci un URL in cui possiamo testare oEmbed Read, usa gli endpoint oEmbed per ottenere l'HTML di incorporamento per qualsiasi post o video pubblico sulla Pagina Facebook o Pagina Instagram ufficiale (oppure per ottenere l'HTML di incorporamento per una delle due Pagine). Aggiungi l'HTML di incorporamento restituito alla Pagina in cui visualizzerai il contenuto oEmbed e inseriscilo 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

Gli endpoint oEmbed di Facebook richiedono 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 codice HTML di incorporamento

Per ottenere l'HTML di incorporamento di una Pagina, un post o un video, invia una richiesta all'endpoint oEmbed page, post o video corrispondente:

Sostituisci {url} con l'URL della Pagina, del post o del video 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 un simbolo di barra verticale, altrimenti la richiesta non andrà a buon fine.

Se l'operazione viene eseguita correttamente, l'API risponderà con un oggetto JSON contenente l'HTML di incorporamento di Pagina, post o video e dati aggiuntivi relativi. L'HTML di incorporamento sarà assegnato alla proprietà html.

Consulta il riferimento di ogni endpoint per un elenco di parametri della stringa di query che puoi includere per perfezionare la richiesta. Puoi anche includere in qualsiasi richiesta il parametro della stringa di query fields per specificare i campi da restituire. Se lo ometti, la risposta includerà tutti i campi predefiniti.

• Riferimento Pagina oEmbed
• Riferimento post oEmbed
• Riferimento video oEmbed

Esempio di richiesta Pagina

curl -i -X GET \
 "https://graph.facebook.com/v19.0/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC&access_token=96481..."

Esempio di risposta

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

{
  "provider_url": "https://www.facebook.com",
  "provider_name": "Facebook",
  "height": 500,
  "html": "<div id=\"fb-root\"></div><script async=\"1\" defer=...",
  "type": "rich",
  "version": "1.0",
  "width": 340
}

Formati URL

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

Pagine

https://www.facebook.com/{page-name}
https://www.facebook.com/{page-id}

Post

https://www.facebook.com/{page-name}/posts/{post-id}
https://www.facebook.com/{username}/posts/{post-id}
https://www.facebook.com/{username}/activity/{activity-id}
https://www.facebook.com/photo.php?fbid={photo-id}
https://www.facebook.com/photos/{photo-id}
https://www.facebook.com/permalink.php?story_fbid={post-id}&id={page-or-user-id}
https://www.facebook.com/media/set?set={set-id}
https://www.facebook.com/questions/{question-id}
https://www.facebook.com/notes/{username}/{note-url}/{note-id}

Video

https://www.facebook.com/{page-name}/videos/{video-id}/
https://www.facebook.com/{username}/videos/{video-id}/
https://www.facebook.com/video.php?id={video-id}
https://www.facebook.com/video.php?v={video-id}

SDK JS

Per impostazione predefinita, l'HTML di incorporamento contiene un riferimento alla libreria JavaScript sdk.js. Per ottenere l'HTML di incorporamento senza il riferimento in modo da poterlo caricare separatamente, includi il parametro della stringa della query omitscript=true.

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/oembed_page?url=https%3A%2F%2Fwww.facebook.com%2FCDC" \
  --header "Authorization: Bearer 96481..."