Wrapper Unity Jeux intégrés YouTube expérimental

Ce wrapper vous permet d'accéder au SDK Jeux intégrés YouTube dans Unity C#. Il comporte un plug-in .jslib et un fichier C# pour accélérer votre développement. Il existe également un exemple de projet qui montre comment les utiliser dans votre projet.

Vous pouvez télécharger les packages Unity à partir de notre dépôt d'exemples Playables sample repo.

Utilisation

  1. Vérifiez que la plate-forme de votre projet Unity est définie sur WebGL. Ce paramètre se trouve dans Build Settings (Paramètres de compilation).
  2. Utilisez le WebGLTemplate pour compiler votre jeu pour le Web ou suivez la section Utiliser votre propre fichier index.html et vérifiez que vous avez configuré et initialisé le SDK Web dans votre index.html fichier.
    • WebGLTemplate se trouve dans le package Google-WebGLTemplate-only.unitypackage ou GoogleYTGameWrapper-with-sample.unitypackage. Pour configurer et utiliser ce modèle, suivez les étapes de la section Modèle WebGL.
    • Pour utiliser votre propre fichier Web et index.html, vous devez ajouter deux lignes à votre script de création Unity index.html. Pour en savoir plus sur l'intégration, consultez la section Use your own index.html file.
  3. Ouvrez votre projet dans Unity, puis ouvrez et importez l'un des packages dans votre projet.
    • GoogleYTGameWrapper.unitypackage: contient un plug-in JS pour connecter le SDK Jeux intégrés YouTube et un wrapper C# pour vous aider à le connecter à votre produit.
    • GoogleYTGameWrapper-with-sample.unitypackage: contient le même contenu de fichier que celui du package GoogleYTGameWrapper et un exemple montrant comment utiliser le SDK Jeux intégrés YouTube en C#.
  4. IMPORTANT : Dans votre scène principale, créez un objet de jeu et nommez-le YTGameWrapper. Cet objet de jeu est utilisé pour communiquer avec le pont JS.
  5. IMPORTANT : Ajoutez le code importé YTGameWrapper.cs en tant que composant de script à l'objet de jeu YTGameWrapper.

  6. Si votre projet comporte plusieurs scènes, veillez à ajouter DontDestroyOnLoad au script YTGameWrapper.cs (remarque : les nouvelles versions du script comportent un bouton à bascule DontDestroyOnSceneChange qui est activé par défaut). Cela garantit que le script et l'objet de jeu restent présents tout au long de votre jeu.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. Le composant YTGameWrapper.cs et l'objet de jeu YTGameWrapper sont utilisés pour se connecter au SDK Jeux intégrés YouTube. Utilisez-les pour vous connecter à YouTube. Vous pouvez utiliser un script pour trouver l'objet et le composant, ou les ajouter manuellement au code de votre jeu via l'éditeur Unity.

  8. Vérifiez que vous respectez les exigences techniques de votre projet.

Utiliser votre propre fichier index.html

Si vous n'utilisez pas l'exemple index.html fourni, vous devez ajouter deux lignes de code à votre script de création Unity index.html.

Commencez par ajouter cette ligne au même endroit où votre projet configure des variables pour le conteneur Unity, le canevas, etc.

    var container = document.querySelector("#unity-container");
    var canvas = document.querySelector("#unity-canvas");

    var unityGameInstance = null; // <-- Add this line >

    ...

Ensuite, ajoutez cette ligne dans la fonction createUnityInstance.

    createUnityInstance(canvas, config, (progress) => {
        progressBarFull.style.width = 100 * progress + "%";
    }).then((unityInstance) => {

        unityGameInstance = unityInstance; // <-- Add this line >

    ...

Exemples

Cette section présente quelques exemples d'utilisation du wrapper C#. Il ne s'agit pas de la liste complète des API disponibles. Pour obtenir la liste complète des API disponibles, consultez le SDK Jeux intégrés YouTube.

sendScore

Cet exemple montre une implémentation de sendScore(int points) en C#:

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;
public int battleScore = 0;

...

// Update the total score and send this to the YouTube Game Wrapper.
public void UpdateScores(int scoreAmt)
{
    battleScore += scoreAmt;
    // ytGameWrapper should be a reference to your YTGameWrapper component.
    ytGameWrapper.SendGameScore(battleScore);
}

onPause

Voici un exemple de la façon dont un jeu peut écouter les événements Pause provenant de YT Playables, afin de mettre en pause son moteur si nécessaire :

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;
public bool gameIsPaused = false;

...
void Start()
{
    // Sets the OnPause callback with the YT Playables SDK
    ytGameWrapper.SetOnPauseCallback(PauseTheGameCallback);
}

// Pause game callback, will pause the game when called.
public void PauseTheGameCallback()
{
    gameIsPaused = true;
}

saveData

Voici un exemple d'utilisation de saveData, qui l'envoie au SDK YT Playables :

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;

...

// Saves the current score of the game and converts it to a JSON format.
public void SaveScore(int scoreAmt)
{
    SaveGameData("{\"BestScore\": \"" + scoreAmt.ToString() + "\"}");
}

public void SaveGameData(string saveString)
{
    if (string.IsNullOrEmpty(saveString)) return;

    // Sends save data to the YT Playables SDK
    ytGameWrapper.SendGameSaveData(saveString);
}

loadData

Voici un exemple d'utilisation de loadData, qui l'envoie au SDK YT Playables :

...
using UnityEngine;
using YTGameSDK;
...

[Serializable]
public class LoadedScores
{
    public int BestScore;
    public float BestTime;
}

public YTGameWrapper ytGameWrapper;

...

void Start()
{
    ytGameWrapper.LoadGameSaveData(LoadSaveGameDataReturned);
}

public void LoadSaveGameDataReturned(string data)
{
    if (!string.IsNullOrEmpty(data))
    {
        LoadedScores loadedScores = JsonUtility.FromJson<LoadedScores>(data);
        Debug.Log("LoadSaveGameDataReturned > Score <" + loadedScores.BestScore.ToString()
                  +   "> Time <" + loadedScores.BestTime.ToString("0.00"));
    }
}

requestInterstitialAd

Voici un exemple d'utilisation de requestInterstitialAd, qui indique qu'il est temps d'afficher une annonce interstitielle, si elle est disponible. Pour obtenir les meilleurs résultats, effectuez cet appel pendant une pause dans le jeu, par exemple à la fin d'un niveau.

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;

...

// At the end of a round send a request to show an interstitial Ad, if one is
//  available an Ad will be shown and Pause Game Callback should be called.

// EXAMPLE: send and forget
public void RequestInterstitialAd()
{
    ytGameWrapper.RequestInterstitialAd();
}

// EXAMPLE: send and react to if an Ad was shown
public void RequestInterstitialAd()
{
    int status = ytGameWrapper.RequestInterstitialAd();
    if (status == 0)
    {
        // Ad request was successful, do some action.
    }
}

requestRewardedAd

Voici un exemple d'utilisation de requestRewardedAd. Cette méthode est utilisée lorsqu'un utilisateur a choisi de regarder une annonce avec récompense en échange d'une récompense dans votre jeu. Si une annonce est disponible, elle sera présentée à l'utilisateur.

...
using YTGameSDK;
...

public YTGameWrapper ytGameWrapper;

...

public void RequestRewardedAd()
{
    // Register callback for Rewarded Ads. If an Ad is available one will be
    //  shown. Pause Game Callback should be called. Any ID is fine as long as
    //  its identifyable for your game.
    ytGameWrapper.RequestRewardedAd("my-reward-ad-id-123", (rewardEarned) => {
        if (rewardEarned) {
            // Rewarded Ad is earned, reward the user.
        } else {
            // Rewarded Ad not earned, take the appropriate action
        }
    });
}

Utiliser l'exemple de modèle WebGL de YouTube

Sauf si votre projet Unity est très volumineux, vos fichiers .wasm et .data compilés doivent respecter notre limite de taille de fichier individuelle. Si tel est le cas, aucune compression supplémentaire ne doit être effectuée de votre côté pour ces fichiers, car ils seront automatiquement compressés lors de l'envoi de vos fichiers Playables. Cette compression automatique vérifie également que votre fichier .wasm respecte l' exigence de taille de bundle initiale. Par exemple, un fichier .wasm d'environ 25 Mio sera compressé à environ 7 Mio.

Si, pour une raison quelconque, vos fichiers dépassent la limite de taille de fichier individuelle maximale, il est préférable d'utiliser la compression ZIP pour vérifier qu'ils respectent cette limite. La compression Playables ne recompressera pas ces fichiers.

Modèle WebGL

  1. Suivez les instructions du package Unity ci-dessus pour la configuration initiale. Veillez à utiliser Google-WebGLTemplate-only.unitypackage ou GoogleYTGameWrapper-with-sample.unitypackage et à importer tous les fichiers du dossier WebGLTemplates/YTGameWrapperTemplate/.
    • Remarque : Si vous n'avez pas encore importé YTGameWrapper.cs et UnityYTGameSDKLib.jslib, vous devez également les importer.
  2. Définissez votre modèle WebGL sur YTGameWrapperTemplate. Ce paramètre se trouve dans Edit -> Project settings -> Player -> WebGL tab -> Resolution and Presentation section (Modifier > Paramètres du projet > Lecteur > Onglet WebGL > Section Résolution et présentation).
    • Remarque : La largeur et la hauteur du canevas par défaut sont définies sur 100% dans le modèle. Par conséquent, ces paramètres Unity n'ajusteront rien.
  3. Assurez-vous que votre Compression Format (Format de compression) est défini sur "Disabled" (Désactivé). Ce paramètre se trouve dans Project settings -> Player -> WebGL tab -> Publishing Settings section (Paramètres du projet > Lecteur > Onglet WebGL > Section Paramètres de publication).
  4. Compilez pour WebGL dans la fenêtre Build Settings (Paramètres de compilation), puis passez à l'étape 7 ou 5 en fonction des besoins de votre projet.
  5. Ne suivez les étapes 5 et 6 que si la compression est utilisée : une fois votre projet compilé, accédez à l'emplacement de votre dossier de compilation et ouvrez le dossier Build. Recherchez les fichiers .wasm ou .data de vos projets qui doivent être compressés pour respecter les limites de taille de fichier individuelles, puis compressez ces fichiers. Veillez à supprimer les fichiers .wasm/.data d'origine qui ont été compressés, car vous enverrez les fichiers *.wasm.zip et *.data.zip à la place.
    • Remarque : Si vous utilisez un Mac, vous pouvez effectuer un clic droit sur le fichier et sélectionner "Compresser *". Sur un PC, vous pouvez effectuer un clic droit sur le fichier et sélectionner "Compresser dans un fichier ZIP".
  6. Ne suivez cette étape que si vous avez effectué l'étape 5 : mettez à jour le fichier index.html créé à partir de YTGameWrapperTemplate pour charger les fichiers compressés et les décompresser.
    • Vers la fin des fichiers index.html, vous trouverez Path 1 et vous devrez commenter la ligne suivante : InitUnitySection();.
    • Vers la fin des fichiers index.html, vous trouverez Path 2 et vous devrez commenter la ligne suivante : loadResources(InitUnitySection);.
  7. Lorsque vous envoyez votre projet pour certification, vous devez envoyer tous les fichiers créés à partir d'Unity à l'emplacement de compilation de l'étape 4. Si vous avez suivi les étapes 5 et 6, incluez également ces fichiers.

Mettre à niveau les exemples fournis pour utiliser le pipeline de rendu universel (URP)

L'une des dernières avancées des versions plus récentes d'Unity est qu'elles utilisent le pipeline de rendu universel (URP). Pour mettre à niveau l'exemple afin que tout soit rendu correctement :

  1. Commencez par importer le package GoogleYTGameWrapper-with-sample.unitypackage dans un projet nouveau ou existant.
  2. Accédez à la fenêtre Render Pipeline Converter : Window -> Rendering -> Render Pipeline Converter (Fenêtre > Rendu > Convertisseur de pipeline de rendu).
  3. Sélectionnez Rendering Settings (Paramètres de rendu), Material Upgrade (Mise à niveau des matériaux) et Readonly Material Converter (Convertisseur de matériaux en lecture seule).
  4. Sélectionnez ensuite Initialize and Convert (Initialiser et convertir), attendez la fin de l'opération, et l'exemple devrait être prêt pour URP.

Fractionner les éléments de votre projet Unity (chargement différé)

L'un des principaux problèmes que les développeurs ont souligné lors de l'utilisation d'Unity est de respecter les exigences de taille de fichier individuelle et les exigences de taille totale du bundle.

Le chargement différé des éléments est une excellente optimisation que vous pouvez apporter à votre projet, car vous pouvez charger les éléments, les niveaux et les données en fonction des besoins. Notre équipe de certification peut renoncer aux restrictions générales de taille de fichier si cela est fait correctement, car votre jeu complet ne sera pas chargé au début, mais au fur et à mesure que l'utilisateur navigue dans votre produit.

Pour faciliter le chargement approprié, Unity propose plusieurs façons de fractionner vos éléments, en vérifiant que vos groupes d'éléments individuels respectent les limites de taille et que vous chargez le contenu au fil du temps. Nous vous suggérons d'utiliser Addressables ou Asset Bundles.

Système Addressables

Addressables vous permet d'identifier différents fichiers qui doivent être chargés ensemble, et Unity gère la majeure partie de l'empaquetage pour vous. Unity fournit également des outils pour gérer la taille des fichiers et vous aider à vous assurer que vous ne dupliquez pas les éléments.

Pour utiliser Addressables, vous devez importer le package Addressables via le gestionnaire de packages dans Unity, puis baliser vos éléments dans des groupes Addressables. Pour en savoir plus, consultez la documentation Unity.

Asset Bundles

Les Asset Bundles sont utiles, car vous pouvez fractionner votre projet et charger des éléments à la volée. Ils sont utiles pour les contenus téléchargeables, les packs de niveaux, les nouveaux personnages, etc. Les Asset Bundles sont idéaux pour le chargement et le regroupement de contenu autogéré. Vous pouvez les utiliser en balisant vos éléments dans des bundles spécifiques, puis en chargeant les bundles selon vos besoins. Pour en savoir plus, consultez la documentation sur les Asset Bundles d'Unity.

Consultez la documentation de référence complète de l'API YT Playables.