Mettre à jour les succès gérés par le titre

Cette rubrique couvre les points suivants :

Avant de commencer
Déverrouiller un succès
Mettre à jour la progression de l’achèvement d’un succès
Résolution des problèmes

Avant de commencer

Votre produit utilise l’ensemble complet des fonctionnalités des services XBOX. Les nouveaux produits démarrent avec des services XBOX limités, et les succès et le gamerscore ne sont pas disponibles tant que votre produit n’a pas été intégré. Pour plus d’informations, consultez Demander l’intégration du produit pour activer l’ensemble des services XBOX.
Vous avez configuré le succès dans Partner Center et publié la configuration des services XBOX dans votre bac à sable de développement. Pour plus d’informations, consultez Configurer les succès gérés par le titre dans Partner Center.
Votre kit de développement ou votre PC Windows utilise le même bac à sable de développement, et vous vous connectez avec un compte de test qui a accès à ce bac à sable. Pour plus d’informations, consultez Vue d’ensemble des sandboxes des services XBOX.
Votre jeu a initialisé Gaming Runtime, puis a appelé XblInitialize avec une structure XblInitArgs dont le membre scid contient votre ID de configuration de service (SCID). Le SCID respecte la casse. Pour plus d’informations, consultez Utilisation des API des services XBOX.
Vous avez connecté un utilisateur et créé un XblContextHandle pour cet utilisateur en appelant XblContextCreateHandle.

Pour réinitialiser les succès d’un compte de test entre deux séries de tests, utilisez l’outil Player Data Reset (XblPlayerDataReset.exe). Pour réinitialiser un joueur à partir de son XUID, le compte de développeur avec lequel vous vous connectez à l’aide de XblDevAccount.exe doit disposer de l’autorisation Tools Access au niveau du produit.

Déverrouiller un succès

Une fois vos succès configurés via Partner Center et publiés dans votre bac à sable de développement, votre titre peut les déverrouiller en appelant l’API XblAchievementsUpdateAchievementAsync. Pour plus d’informations, consultez l’exemple de code de la section suivante. Pour déverrouiller un succès, définissez percentComplete sur 100. Si l’utilisateur est en ligne, la demande est immédiatement envoyée au service Achievements des services XBOX et déclenche les expériences utilisateur suivantes.

L’utilisateur reçoit une notification de succès déverrouillé.
Le succès spécifié apparaît comme déverrouillé dans la liste des succès de l’utilisateur pour le titre.
Le succès déverrouillé est ajouté au flux d’activité de l’utilisateur.

L’expérience utilisateur est visuellement identique pour les succès, qu’ils utilisent les succès basés sur les événements ou les succès gérés par le titre.

Si l’utilisateur est hors connexion, la demande de déverrouillage est mise en file d’attente localement sur l’appareil de l’utilisateur. Lorsque la connectivité réseau est rétablie, la demande est automatiquement envoyée au service Achievements (aucune action du jeu n’est nécessaire pour la déclencher), et les expériences utilisateur précédentes se produisent comme décrit.

Mettre à jour la progression de l’achèvement d’un succès

Pour mettre à jour la progression d’un utilisateur vers le déverrouillage d’un succès, appelez XblAchievementsUpdateAchievementAsync. Définissez l’argument percentComplete sur un nombre entier compris entre 1 et 100. Pour plus d’informations, consultez l’exemple de code suivant. La progression d’un succès ne peut qu’augmenter. Si percentComplete est défini sur un nombre inférieur à la dernière valeur percentComplete du succès, la mise à jour est ignorée. Par exemple, si la valeur percentComplete du succès avait précédemment été définie sur 75, l’envoi d’une mise à jour avec une valeur de 25 est ignoré. Le succès reste affiché comme achevé à 75 pour cent. Si percentComplete est défini sur 100, le succès est déverrouillé. Si percentComplete est défini sur un nombre supérieur à 100, l’API se comporte comme si vous aviez défini le nombre sur exactement 100.

Mettre à jour les succès du titre actuel

Vous pouvez mettre à jour les succès du titre actuel en appelant XblAchievementsUpdateAchievementAsync, comme suit. API C plate

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.
    auto result = XAsyncGetStatus(asyncBlock, false);
    if (SUCCEEDED(result))
    {
        // The achievement was updated.
    }
    else if (result == HTTP_E_STATUS_NOT_MODIFIED)
    {
        // The achievement wasn't updated.
    }
    else
    {
        // The achievement failed to update.
    }
};

HRESULT hr = XblAchievementsUpdateAchievementAsync(
    xboxLiveContext,
    xboxUserId,
    achievementId.c_str(),
    percentComplete,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Mettre à jour les succès d’un autre titre

Vous pouvez mettre à jour les succès d’un autre titleId à l’aide de XblAchievementsUpdateAchievementForTitleIdAsync, comme suit. API C plate

auto asyncBlock = std::make_unique<XAsyncBlock>();
asyncBlock->queue = queue;
asyncBlock->context = nullptr;
asyncBlock->callback = [](XAsyncBlock* asyncBlock)
{
    std::unique_ptr<XAsyncBlock> asyncBlockPtr{ asyncBlock }; // Take over ownership of the XAsyncBlock*.
    auto result = XAsyncGetStatus(asyncBlock, false);
    if (SUCCEEDED(result))
    {
        // The achievement was updated.
    }
    else if (result == HTTP_E_STATUS_NOT_MODIFIED)
    {
        // The achievement wasn't updated.
    }
    else
    {
        // The achievement failed to update.
    }
};

HRESULT hr = XblAchievementsUpdateAchievementForTitleIdAsync(
    xboxLiveContext,
    xboxUserId,
    titleId,
    scid,
    achievementId.c_str(),
    percentComplete,
    asyncBlock.get()
);
if (SUCCEEDED(hr))
{
    // The call succeeded, so release the std::unique_ptr ownership of XAsyncBlock* because the callback will take over ownership.
    // If the call fails, std::unique_ptr will keep ownership and delete XAsyncBlock*.
    asyncBlock.release();
}

Pour plus d’informations, consultez les rubriques suivantes :

Résolution des problèmes

Pour regrouper un HRESULT d’échec dans une catégorie exploitable, appelez XblGetErrorCondition. Ne réessayez pas vous-même les mises à jour qui ont échoué. Si une mise à jour échoue en raison d’un problème de réseau ou d’authentification, d’une limitation (HTTP 429), d’une erreur de serveur (HTTP 5xx) ou d’une erreur non classée, XSAPI la met en file d’attente sous forme d’événement hors connexion et l’envoie lorsque l’appareil est de nouveau en ligne. Dans ce cas, XAsyncGetStatus retourne le résultat de la mise en file d’attente de l’événement, qui est normalement S_OK. Si vous réessayez, le service peut recevoir la mise à jour deux fois. Les résultats suivants peuvent parvenir à votre jeu :

Résultat	Cause possible	Action à effectuer
`HTTP_E_STATUS_NOT_MODIFIED` (`XblErrorCondition::Http304NotModified`)	Le succès est déjà déverrouillé, ou la nouvelle valeur de progression n’est pas supérieure à la valeur enregistrée par le service.	Aucune action n’est requise.
Un autre statut HTTP 4xx, tel que 400, 403 ou 404	Le service a rejeté la requête, par exemple parce que l’ID du succès n’est pas configuré pour votre titre ou votre bac à sable.	Vérifiez l’ID du succès et la configuration de votre titre. Une nouvelle tentative de la même requête échouera de la même manière.
`E_INVALIDARG`	Le contexte, l’ID du succès ou le bloc asynchrone est null.	Vérifiez les arguments. Passez une valeur `percentComplete` comprise entre 1 et 100.
`E_XBL_NOT_INITIALIZED`	XSAPI n’est pas initialisé.	Appelez `XblInitialize` avant de mettre à jour les succès.

Retour en haut de cette rubrique.

XBOX Services

PlayFab

Avant de commencer

Déverrouiller un succès

Mettre à jour la progression de l’achèvement d’un succès

Mettre à jour les succès du titre actuel

Mettre à jour les succès d’un autre titre

Résolution des problèmes

​Avant de commencer

​Déverrouiller un succès

​Mettre à jour la progression de l’achèvement d’un succès

​Mettre à jour les succès du titre actuel

​Mettre à jour les succès d’un autre titre

​Résolution des problèmes

Avant de commencer

Déverrouiller un succès

Mettre à jour la progression de l’achèvement d’un succès

Mettre à jour les succès du titre actuel

Mettre à jour les succès d’un autre titre

Résolution des problèmes