Business Management APIs

Primi passi

Scopri come implementare la gestione delle risorse creative.

La gestione delle risorse creative è disponibile solo per partner selezionati. Contatta il tuo partner di Meta per maggiori informazioni.

Requisiti

Per usare questa API, hai bisogno di:

Autorizzazioni

Dopo aver effettuato l'accesso alla tua app, dovrai richiedere agli utenti le seguenti autorizzazioni:

  • business_creative_management: consente di gestire le cartelle delle creatività business e le creatività business. Obbligatorio per tutti gli endpoint dell'API Business Creative Asset Manager.
  • business_creative_insights: consente di accedere agli insight sulle risorse delle creatività business.
  • business_management: consente di gestire gli utenti business e di accettare le richieste di accordi di collaborazione.

Limitazioni

  • L'utente dell'app (l'inserzionista) deve essere un amministratore del Business Manager rappresentati dall'ID del Business Manager.

Passaggio 1: crea una cartella delle creatività business

Crea una cartella delle creatività business per conto del Business Manager dell'inserzionista effettuando una richiesta POST all'endpoint {business-id}/creative_folders. In questo caso, {business-id} è l'ID del Business Manager dell'inserzionista.

È necessaria l'autorizzazione business_creative_management per questa azione.

Esempio di richiesta

curl -X POST \
  -F 'name={folder-name}' \
  -F 'access_token={access-token}' \
  https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders

Esempio di risposta

{ “id”: “{business-creative-folder-id}” }

Puoi anche creare delle sottocartelle.

Passaggio 2: aggiungi creatività alle cartelle

Aggiungi risorse creative esistenti a una cartella effettuando una richiesta POST a {business-id}/images o {business-id}/videos. Hai bisogno dell'autorizzazione business_creative_management per questa azione.

Aggiunta di immagini

Esempio — Per aggiungere un'immagine:

curl -X POST \
  -F 'bytes={image-content-in-bytes-format}' \
  -F 'name={image-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph.facebook.com/{version}/{business-id}/images

Risposta

{
  "images":{
    "{image-name}":{
      "id":"{business-image-id}",
      "hash":"{hash}",
      "url":"{image-url}"
    }
  }
}

Caricamento di video

Carica un video in un'unica richiesta se è inferiore a pochi megabyte oppure caricalo in porzioni. Effettua la chiamata API per il caricamento del video su graph-video.facebook.com invece di graph.facebook.com.

Esempio: invia una richiesta POST a {business-id}/video e includi il nome del tuo video, l'origine e l'ID della cartella delle creatività business.

curl -X POST \
  -F 'name={video-name}' \
  -F 'source='@{video-path}'' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  https://graph-video.facebook.com/{version}/{business-id}/videos

Risposta

{ 
    "success": true, 
    "business_video_id": "{business-video-id}" 
}

Caricamento dei video in porzioni

Per video di dimensioni maggiori, invia una richiesta start, una o più richieste transfer e una richiesta finish.

Per effettuare una richiesta start e creare una sessione di caricamento di video, invia una richiesta POST a /{business-id}/videos, imposta il campo upload_phase su start e specifica file_size in byte.

curl -X POST \
  -F 'title={video-name}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'access_token={access-token}' \
  -F 'upload_phase=start' \
  -F 'file_size={video_file_size_in_bytes}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Esempio di risposta

{
  "upload_session_id": "{session-id}",
  "business_video_id": "{business-video-id}",
  "video_id": "{video-id}",
  "start_offset": "0",
  "end_offset": "52428800"
}

Per caricare [0, 52428800] dal tuo video, suddividi il file in porzioni in base agli offset di inizio e fine, quindi invia quelle porzioni con le richieste transfer. Ti inviamo nuovi offset per ogni porzione. Usali per caricare ogni porzione.

Esempio: invia la prima porzione

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'upload_session_id={session-id}' \
  -F 'start_offset=0' \
  -F 'video_file_chunk=@{binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

In caso di azione eseguita correttamente, rispondiamo con gli offset per la porzione successiva:

{
 "start_offset": "52428800",    //Start byte position of the next file chunk.
 "end_offset": "104857601"      //End byte position of the next file chunk.
}

Taglia e carica la seconda porzione con l'intervallo [52428800, 104857601] dal tuo file e inviala:

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=transfer' \
  -F 'start_offset=52428801' \
  -F 'upload_session_id={your-upload-sesson-id}' \
  -F 'video_file_chunk={binary-chunk-filename}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Invia tutte le porzioni aggiuntive fino a quando start_offset non corrisponde a end_offset:

{
  "start_offset": "152043520",
  "end_offset": "152043520"
}

Questo significa che hai caricato l'intero file. Ora devi pubblicare questo video e chiudere la sessione di caricamento.

curl -X POST \
  -F 'title={video-name}' \
  -F 'access_token={access-token}' \
  -F 'creative_folder_id={business-creative-folder-id}' \
  -F 'upload_phase=finish' \
  -F 'upload_session_id={session-id}' \
  https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos

Se ricevi degli errori durante un caricamento, puoi riprovare a caricare quella porzione specifica. Di solito, gli errori sono dovuti a problemi di risposta. Riprova a caricare la porzione non riuscita. Per maggiori informazioni sugli errori, consulta:

Una volta caricate le creatività in una cartella, gli inserzionisti con accesso a quella cartella possono creare inserzioni su Gestione inserzioni o con l'API Marketing.

Tutte le creatività caricate vengono mostrate nell'interfaccia utente Gestione inserzioni > Media Selection (Selezione contenuto multimediale). Puoi usarle in Ads Creation (Creazione inserzioni) e Ads Editing (Modifica inserzioni). Inoltre, le cartelle e le risorse creative sono disponibili nello strumento Libreria multimediale del Business Manager in Business Manager > Libreria multimediale.

Passaggio 3: fornisci l'URL del deep link alla risorsa e crea l'inserzione o il post

Per ottenere l'URL del deep link per una risorsa specifica, interroga il campo media_library_url dell'immagine o della risorsa video caricata:

curl -X GET \  
  -F 'access_token={partner-access-token}' \
https://graph.facebook.com/v<API_VERSION>/<asset_id>?fields=media_library_url

Per usare il tuo deep link per creare un'inserzione o un post della Pagina, aggiungi &action=CREATE_AD o &action=CREATE_POST alla fine del link:

https://business.facebook.com/asset_library/business_creatives/?object_id=<OBJECT_ID>&action=CREATE_AD