Gestion des versions de la plate-forme

La plate-forme Facebook prend en charge la gestion des versions afin que les créateurs d’applications puissent déployer les modifications au fil du temps. Ce document explique en quoi les SDK et les API sont concernés par les versions et comment utiliser ces versions dans vos requêtes.

Gestion des versions

Les API et les SDK ne partagent pas tous le même système de gestion des versions. Dans le cas de l’API Graph, par exemple, la numérotation et la fréquence sont différentes de celles du SDK Facebook pour iOS. Tous les SDK Facebook offrent la possibilité d’interagir avec différentes versions de nos API. Plusieurs versions d’API ou de SDK peuvent exister en même temps, avec des fonctionnalités différentes dans chaque version.

Quelle est la dernière version de l’API Graph ?

Dernière version de l’API Graph : v21.0

Pourquoi existe-t-il plusieurs versions ?

L’objectif de la gestion des versions est de permettre aux développeurs de créer des applications afin de déterminer à l’avance à quel moment une API ou un SDK est susceptible d’évoluer. Les versions facilitent le développement web, mais sont également essentielles pour le développement mobile, car une personne qui utilise votre application sur son téléphone peut mettre longtemps avant d’effectuer une mise à niveau (dans le meilleur des cas).

Chaque version est conservée au moins deux ans après sa sortie, ce qui vous donne une idée précise de la durée de fonctionnement de votre application, et de la fréquence de mise à jour vers des versions plus récentes.

Calendriers des versions

Le fonctionnement de chaque version est garanti pendant au moins deux ans. Une version deviendra inutilisable deux ans après la date de sortie de la version suivante. Par exemple, si l’API version 2.3 sort le 25 mars 2015 et que l’API version 2.4 sort le 7 août 2015, la version 2.3 expirera le 7 août 2017, soit deux ans après la sortie de la version 2.4.

Dans le cas des API, lorsqu’une version n’est plus utilisable, tous les appels effectués vers celle-ci sont adressés, par défaut, à la version suivante utilisable la plus ancienne. Voici un exemple de calendrier :

Pour les SDK, une version restera toujours disponible, puisqu’il s’agit d’un package à télécharger. Toutefois, il est possible que le SDK dépende d’API ou de méthodes qui ne fonctionnent plus. Vous devez donc en déduire que le SDK qui a expiré n’est plus fonctionnel.

Vous trouverez des informations spécifiques sur les calendriers de versions, les modifications et les dates de sortie sur notre page de changelog.

Est-ce que tous les éléments resteront inchangés dans une version ?

Facebook se réserve le droit d’apporter des modifications à toute API dans les plus brefs délais pour corriger les problèmes associés à la sécurité et à la confidentialité. Ces modifications sont rares, mais elles existent.

Que se passe-t-il si je n’indique pas de version pour une API ?

Un appel d’API sans spécification de version est appelé appel sans version. Par exemple, disons que la version actuelle est la version 4.0. L’appel se présente comme suit :

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

Le même appel sans version se présente comme suit :

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

Un appel sans version utilise la version indiquée dans la carte Mettre à niveau la version de l’API d’Espace App, sous Paramètres > Avancés. Dans l’exemple suivant, la version définie dans le tableau de bord de l’application est la version 2.10 et l’appel sans version équivaut à :

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

Nous recommandons d’indiquer la version dans la mesure du possible.

Restrictions

Vous ne pouvez pas effectuer des appels d’API sans version au SDK Facebook pour JavaScript.

Mon application peut-elle passer des appels aux versions plus anciennes que la version actuelle ?

Vous pouvez spécifier des versions plus anciennes dans vos appels d’API dès lors qu’elles sont disponibles et que votre application a passé des appels vers ces versions. Par exemple, si votre application a été créée après la sortie de la version 2.0 et qu’elle passe des appels avec cette version, elle pourra continuer à passer des appels à la version 2.0 jusqu’à expiration de cette dernière, même après la sortie de nouvelles versions. En revanche, si vous avez créé votre application après la sortie de la version 2.0, mais que vous n’avez passé aucun appel avant la version 2.2, votre application ne sera pas en mesure de passer des appels avec les versions 2.0 ou 2.1. Elle pourra uniquement passer des appels à l’aide des versions 2.2 et ultérieures.

Gestion des versions de l’API Marketing

L’API Marketing possède son propre schéma de gestion des versions. Les numéros de version et leurs calendriers sont différents de ceux de l’API Graph.

En savoir plus sur la gestion des versions de l’API Marketing

Envoi de requêtes avec version

API Graph

Qu’ils soient principaux ou étendus, tous les points de terminaison de l’API Graph sont disponibles par le biais d’un processus avec version. Vous trouverez un guide complet sur l’utilisation des versions avec l’API Graph dans notre Guide de démarrage rapide de l’API Graph.

Boîtes de dialogue

Les processus avec version ne valent pas seulement pour les points de terminaison d’API. Ils sont également appropriés pour les boîtes de dialogue et les plugins sociaux. Par exemple, si vous souhaitez générer la boîte de dialogue Facebook Login pour une application web, vous pouvez ajouter un numéro de version avant le point de terminaison qui génère la boîte de dialogue :

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

Plugins sociaux

Si vous utilisez les versions HTML5 ou xfbml de nos plugins sociaux, la version rendue sera déterminée par celle spécifiée lors de l’initialisation du SDK JavaScript.

Si vous insérez une version de lien externe ou iFrame de l’un de nos plugins, le chemin source du plugin doit être précédé du numéro de version :

<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>

Création de requêtes avec version à partir de SDK

Si vous utilisez le SDK Facebook pour iOS, Android ou JavaScript, l’exécution d’appels de gestion de versions est en grande partie automatique. Notez que cela diffère du système de gestion des versions propre à chaque SDK.

JavaScript

Le SDK JavaScript ne peut utiliser des versions différentes de l’API que si vous utilisez le chemin sdk.js.

Si vous utilisez FB.init() à partir du SDK JavaScript, vous devez utiliser le paramètre de version, comme suit :

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

Si vous définissez l’indicateur de version dans l’init, le chemin appelé sera automatiquement précédé de la version pour tout appel effectué vers FB.api(). Cela vaut également pour toute boîte de dialogue Facebook Login qui serait appelée. Vous obtiendrez la boîte de dialogue Facebook Login pour cette version de l’API.

Si nécessaire, vous pouvez écraser une version en l’ajoutant simplement avant le chemin du point de terminaison dans l’appel FB.api().

iOS

Chaque version du SDK Facebook pour iOS qui est publiée est liée à la version disponible à la date de sortie. Cela signifie que si vous procédez à une mise à niveau vers un nouveau SDK, vous effectuez également une mise à niveau vers la version la plus récente de l’API (bien que vous puissiez préciser manuellement toute version d’API antérieure avec [FBSDKGraphRequest initWithGraphPath]). La version de l’API est indiquée avec chaque version du SDK Facebook pour iOS.

Comme c’est le cas avec le SDK JavaScript, la version précède tout appel effectué vers l’API Graph par le biais du SDK Facebook pour iOS. Par exemple, si v2.7 était la version la plus récente de l’API, l’appel /me/friends, utilisé dans l’exemple de code suivant, appellera en réalité /v2.7/me/friends :

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

Vous pouvez écraser la version de l’appel avec [FBSDKGraphRequestConnection overrideVersionPartWith].

Android

Chaque version du SDK Facebook pour Android qui est publiée est liée à la version disponible à la date de sortie. Cela signifie que si vous procédez à une mise à niveau vers un nouveau SDK, vous effectuez également une mise à niveau vers la version la plus récente de l’API (bien que vous puissiez préciser manuellement toute version d’API avec GraphRequest.setVersion()). La version de l’API est indiquée avec chaque version du SDK Facebook pour Android.

Comme c’est le cas avec le SDK JavaScript, la version précède tout appel effectué vers l’API Graph par le biais du SDK Facebook pour Android. Par exemple, si v2.7 était la version la plus récente de l’API, l’appel /me, utilisé dans l’exemple de code suivant, appellera en réalité /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();

Vous pouvez écraser la version de l’appel avec GraphRequest.setVersion().