Gestione delle versioni della piattaforma

La Piattaforma Facebook supporta la gestione delle versioni, in modo che i creatori di app possano implementare modifiche nel tempo. Questo documento spiega il modo in cui gli SDK e le API sono interessati dalle versioni e il modo di utilizzo di tali versioni nelle richieste.

Gestione delle versioni

Non tutte le API e tutti gli SDK condividono lo stesso sistema di gestione delle versioni. Ad esempio, la versione dell'API Graph viene creata con tempistiche e una numerazione diversi rispetto all'SDK di Facebook per iOS. Tutti gli SDK di Facebook supportano la possibilità di interagire con versioni diverse delle nostre API. Possono coesistere più versioni di API o SDK, ciascuna con diverse funzionalità.

Qual è la versione dell'API Graph più recente?

La versione dell'API Graph più recente è la v21.0

Perché abbiamo le versioni?

L'obiettivo della gestione delle versioni consiste nel dare agli sviluppatori che creano le app la possibilità di capire in anticipo quando potrebbero cambiare un'API o un SDK. Supportano lo sviluppo web, ma sono fondamentali per lo sviluppo mobile, perché una persona che utilizza l'app sul proprio telefono potrebbe impiegare molto tempo per eseguire l'aggiornamento (o potrebbe non eseguirlo affatto).

Ogni versione rimarrà disponibile per almeno 2 anni dal rilascio, fornendoti tempistiche precise in merito a quanto tempo la tua app rimarrà funzionante e per quanto tempo dovrai aggiornarla alle versioni più recenti.

Programmazioni della versione

Si garantisce il funzionamento di ogni versione per almeno 2 anni. Una versione non sarà più utilizzabile 2 anni dopo la data di rilascio di quella successiva. Ad esempio, se la versione API 2.3 viene rilasciata il 25 marzo 2015 e la versione API 2.4 viene rilasciata il 7 agosto 2015, la versione 2.3 scadrà il 7 agosto 2017, due anni dopo il rilascio della versione 2.4.

Per le API, quando una versione non è più utilizzabile, tutte le chiamate effettuate a quest'ultima verranno indirizzate alla successiva versione meno recente utilizzabile per impostazione predefinita. Ecco un esempio di sequenza temporale:

Per gli SDK, una versione rimarrà sempre disponibile in quanto si tratta di un pacchetto scaricabile. Poiché l'SDK potrebbe basarsi su API o metodi non più funzionanti, devi presumere che un SDK arrivato a fine vita non sia più funzionante.

Informazioni specifiche sulle tempistiche delle versioni, sulle modifiche e sulle date di rilascio sono disponibili nella nostra pagina del Registro modifiche.

Gli elementi rimarranno del tutto invariati in una versione?

Facebook si riserva il diritto di apportare modifiche a qualsiasi API in un breve periodo di tempo per correggere problemi relativi alla sicurezza o alla privacy. Tali modifiche non si verificano spesso, ma potrebbero risultare necessarie in alcune situazioni.

Cosa succede se non specifico la versione di un'API?

Una chiamata API effettuata senza specificare una versione viene definita una chiamata senza riferimenti alla versione. Ad esempio, supponiamo che la versione attuale sia la versione 4.0. La chiamata è la seguente:

curl -i -X "https://graph.facebook.com/v4.0/{my-user-id}&access_token={access-token}"

La stessa chiamata senza riferimenti alla versione è la seguente:

curl -i -X "https://graph.facebook.com/{my-user-id}&access_token={access-token}"

Una chiamata senza riferimento alla versione utilizza la versione impostata nella scheda della Dashboard gestione app Aggiorna la versione dell'API in Impostazioni > Avanzate. Nell'esempio seguente, la versione impostata nella Dashboard gestione app è la 2.10 e la chiamata senza riferimenti alla versione è equivalente a:

curl -i -X "https://graph.facebook.com/v2.10/{my-user-id}&access_token={access-token}"

Ti consigliamo di specificare sempre la versione ove possibile.

Limitazioni

Non puoi effettuare chiamate API senza riferimenti alla versione all'SDK JavaScript di Facebook.

La mia app può effettuare chiamate a versioni precedenti rispetto a quella attuale?

Puoi specificare versioni precedenti nelle chiamate all'API purché siano disponibili e l'app abbia effettuato chiamate a quella versione. Ad esempio, se l'app è stata creata dopo il rilascio della versione 2.0 ed effettua chiamate usando la versione 2.0, sarà possibile effettuare chiamate alla versione 2.0 fino alla scadenza di tale versione anche dopo il rilascio di versioni più recenti. Se l'app è stata creata dopo la versione 2.0, ma non sono state effettuate chiamate fino alla versione 2.2, l'app non sarà in grado di effettuare chiamate usando la versione 2.0 o fino alla versione 2.1. Potrà effettuare chiamate utilizzando solo la versione 2.2 e successive.

Gestione delle versioni dell'API Marketing

L'API Marketing ha il proprio schema di gestione delle versioni. I numeri di versione e le relative programmazioni sono diversi rispetto a quelli dell'API Graph.

Scopri di più sulla gestione delle versioni dell'API Marketing

Richieste con versioni

API Graph

Indipendentemente dal fatto che siano core o estesi, quasi tutti gli endpoint dell'API Graph sono disponibili attraverso un percorso con versione. È disponibile una guida completa per l'utilizzo delle versioni con l'API Graph nella nostra guida di avvio rapido dell'API Graph.

Finestre di dialogo

I percorsi con versione non valgono solo per gli endpoint API, ma anche per le finestre di dialogo e i plug-in social. Ad esempio, se desideri generare la finestra di dialogo Facebook Login per un'app web, puoi anteporre un numero di versione all'endpoint che genera la finestra di dialogo:

https://www.facebook.com/v21.0/dialog/oauth?
  client_id={app-id}
  &redirect_uri={redirect-uri}

Plug-in social

Se utilizzi le versioni HTML5 o xfbml dei nostri plug-in social, la versione visualizzata sarà determinata da quella specificata durante l'inizializzazione dell'SDK JavaScript.

Se inserisci la versione di un link semplice o un iframe di uno dei nostri plug-in, devi anteporre il numero di versione al percorso di origine del plug-in:

<iframe
  src="//www.facebook.com/v21.0/plugins/like.php?href=https%3A%2F%2Fdevelopers.facebook.com%2Fdocs%2Fplugins%2F&amp;width&amp;layout=standard&amp;action=like&amp;show_faces=true&amp;share=true&amp;height=80&amp;appId=634262946633418" 
  scrolling="no" 
  frameborder="0" 
  style="border:none; overflow:hidden; height:80px;" 
  allowTransparency="true">
</iframe>

Creazione di richieste con versione dagli SDK

Se utilizzi l'SDK di Facebook per iOS, Android o JavaScript, le chiamate di gestione delle versioni vengono effettuate in prevalenza in maniera automatica. Tale azione è distinta dal sistema di gestione delle versioni di ciascun SDK.

JavaScript

L'SDK JavaScript può utilizzare solo versioni API diverse se utilizzi il percorso sdk.js.

Se utilizzi FB.init() dall'SDK JavaScript, devi utilizzare il parametro relativo alla versione, nel modo seguente:

FB.init({
  appId      : '{app-id}',
  version    : 'v21.0'
});

Se imposti il contrassegno della versione in init, qualsiasi chiamata a FB.api() avrà automaticamente la versione anteposta al percorso chiamato. Lo stesso vale per qualsiasi finestra di dialogo per Facebook Login chiamata. Otterrai la finestra di dialogo Facebook Login per la versione specifica dell'API.

Se necessario, puoi sovrascrivere una versione semplicemente anteponendo la versione al percorso dell'endpoint nella chiamata FB.api().

iOS

Ogni versione dell'SDK di Facebook per iOS rilasciata è legata alla versione disponibile alla data di rilascio. Ciò significa che, se esegui l'aggiornamento a un nuovo SDK, anche la versione dell'API viene aggiornata a quella più recente (sebbene tu possa specificare manualmente qualsiasi versione API precedente disponibile con [FBSDKGraphRequest initWithGraphPath]). La versione API viene indicata con il rilascio di ciascuna versione dell'SDK di Facebook per iOS.

Proprio come l'SDK JavaScript, la versione è anteposta a tutte le chiamate effettuate all'API Graph tramite l'SDK di Facebook per iOS. Ad esempio, se v2.7 era la versione più recente dell'API, la chiamata /me/friends, usata nell'esempio di codice seguente, sarà effettuata a /v2.7/me/friends:

[[[FBSDKGraphRequest alloc] initWithGraphPath:@"me/friends"
  parameters:@{@"fields": @"cover,name,start_time"}]
    startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
        (...)
    }];

Puoi sovrascrivere la versione della chiamata con [FBSDKGraphRequestConnection overrideVersionPartWith].

Android

Ogni versione dell'SDK di Facebook per Android rilasciata è legata alla versione disponibile alla data di rilascio. Ciò significa che, se esegui l'aggiornamento a un nuovo SDK, anche la versione dell'API viene aggiornata a quella più recente (sebbene tu possa specificare manualmente qualsiasi versione API precedente disponibile con GraphRequest.setVersion()). La versione API viene indicata con il rilascio di ciascuna versione dell'SDK di Facebook per Android.

Proprio come l'SDK JavaScript, la versione è anteposta a tutte le chiamate effettuate all'API Graph tramite l'SDK di Facebook per Android. Ad esempio, se v2.7 era la versione più recente dell'API, la chiamata /me, usata nell'esempio di codice seguente, sarà effettuata a /v2.7/me:

GraphRequest request = GraphRequest.newGraphPathRequest (
        accessToken,
        "/me/friends",
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters); 
request.executeAsync();

Puoi sovrascrivere la versione della chiamata con GraphRequest.setVersion().