Experimenteller YouTube Playables Unity-Wrapper

Mit diesem Wrapper können Sie in Unity C# auf das YouTube Playables SDK zugreifen. Der Wrapper enthält ein .jslib-Plug-in und eine C#-Datei, um die Entwicklung zu beschleunigen. Außerdem gibt es ein Beispielprojekt, das zeigt, wie Sie diese in Ihrem Projekt verwenden können.

Unity-Pakete können aus unserem Playables Beispiel-Repository heruntergeladen werden.

Nutzung

1. Prüfen Sie, ob die Plattform Ihres Unity-Projekts auf WebGL festgelegt ist. Diese Einstellung finden Sie unter Build Settings (Build-Einstellungen).
2. Verwenden Sie entweder WebGLTemplate, um Ihr Spiel für das Web zu erstellen, oder folgen Sie der Anleitung im Abschnitt Eigene index.html-Datei verwenden und prüfen Sie, ob Sie das Web SDK eingerichtet und initialisiert haben in Ihrer index.html Datei.
   • WebGLTemplate finden Sie im Paket Google-WebGLTemplate-only.unitypackage oder GoogleYTGameWrapper-with-sample.unitypackage. Informationen zum Einrichten und Verwenden dieser Vorlage finden Sie im Abschnitt WebGL-Vorlage.
   • Wenn Sie Ihre eigene Web- und index.html-Datei verwenden möchten, müssen Sie Ihrem index.html-Erstellungsskript für Unity zwei Zeilen hinzufügen. Weitere Informationen finden Sie im Abschnitt Eigene index.html-Datei verwenden für die Integration.
3. Öffnen Sie Ihr Projekt in Unity und importieren Sie dann eines der beiden Pakete in Ihr Projekt.
   • GoogleYTGameWrapper.unitypackage: Enthält ein JS-Plug-in zum Verbinden des YouTube Playables SDK und einen C#-Wrapper, um die Verbindung zu Ihrem Produkt zu erleichtern.
   • GoogleYTGameWrapper-with-sample.unitypackage: Enthält dieselben Dateien wie das GoogleYTGameWrapper-Paket und ein Beispiel, das zeigt, wie Sie das YouTube Playables SDK in C# verwenden.
4. WICHTIG:Erstellen Sie in Ihrer Hauptszene ein neues Spielobjekt und nennen Sie es YTGameWrapper. Dieses Spielobjekt wird für die Kommunikation mit der JS-Bridge verwendet.
5. WICHTIG: Fügen Sie den importierten YTGameWrapper.cs Code als Skript komponente zum YTGameWrapper Spielobjekt hinzu.

6. Wenn Ihr Projekt mehrere Szenen hat, fügen Sie dem YTGameWrapper.cs-Skript DontDestroyOnLoad hinzu. Hinweis: Neue Versionen des Skripts haben eine DontDestroyOnSceneChange-Umschaltfläche, die standardmäßig aktiviert ist. So bleibt das Skript und das Spielobjekt während des gesamten Spiels erhalten.

   GameObject.DontDestroyOnLoad(this.gameObject);
   

7. Die YTGameWrapper.cs-Komponente und das YTGameWrapper-Spielobjekt werden verwendet, um eine Verbindung zum YouTube Playables SDK herzustellen. Verwenden Sie sie, um eine Verbindung zu YouTube herzustellen. Sie können das Objekt und die Komponente entweder mit einem Skript suchen oder sie manuell über den Unity-Editor zu Ihrem Spielcode hinzufügen.

8. Prüfen Sie, ob Sie die technischen Anforderungen für Ihr Projekt erfüllen.

Eigene index.html-Datei verwenden

Wenn Sie nicht das bereitgestellte index.html-Beispiel verwenden, müssen Sie Ihrem index.html-Erstellungsskript für Unity zwei Codezeilen hinzufügen.

Fügen Sie zuerst diese Zeile an derselben Stelle hinzu, an der Ihr Projekt Variablen für den Unity-Container, die Canvas usw. einrichtet.

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

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

    ...

Fügen Sie dann diese Zeile in die Funktion createUnityInstance ein.

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

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

    ...

Beispiele

In diesem Abschnitt finden Sie einige Beispiele für die Verwendung des C#-Wrappers. Dies ist keine vollständige Liste der verfügbaren APIs. Die vollständige Liste der verfügbaren APIs finden Sie im YouTube Playables SDK.

sendScore

Dieses Beispiel zeigt eine Implementierung von sendScore(int points) in 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

Dieses Beispiel zeigt, wie ein Spiel auf Pause-Ereignisse von YouTube Playables reagieren kann, um die Engine bei Bedarf zu pausieren:

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

Dieses Beispiel zeigt, wie Sie saveData verwenden und an das YouTube Playables SDK senden:

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

Dieses Beispiel zeigt, wie Sie loadData verwenden und an das YouTube Playables SDK senden:

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

Dieses Beispiel zeigt, wie Sie requestInterstitialAd verwenden, um anzugeben, dass es ein guter Zeitpunkt ist, eine Interstitial-Anzeige zu präsentieren, falls verfügbar. Die besten Ergebnisse erzielen Sie, wenn Sie diesen Aufruf während einer Pause im Spiel ausführen, z. B. am Ende eines Levels.

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

Dieses Beispiel zeigt, wie Sie requestRewardedAd verwenden. Diese Funktion wird verwendet, wenn ein Nutzer sich entschieden hat, sich eine Anzeige mit Prämie anzusehen, um eine Belohnung in Ihrem Spiel zu erhalten. Wenn eine Anzeige verfügbar ist, wird sie dem Nutzer präsentiert.

...
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
        }
    });
}

Beispiel-WebGL-Vorlage von YouTube verwenden

Sofern Sie kein sehr umfangreiches Unity-Projekt haben, sollten Ihre erstellten .wasm und .data Dateien unter dem Limit für die individuelle Dateigröße liegen. In diesem Fall ist keine zusätzliche Komprimierung dieser Dateien erforderlich, da sie beim Einreichen Ihrer Playable-Dateien automatisch komprimiert werden. Bei dieser automatischen Komprimierung wird auch geprüft, ob Ihre ` .wasm`-Datei die Anforderungen an die anfängliche Bundle-Größe erfüllt. Beispiel: Eine .wasm-Datei mit einer Größe von etwa 25 MB wird auf etwa 7 MB komprimiert.

Wenn Ihre Dateien aus irgendeinem Grund das Limit für die maximale individuelle Dateigröße überschreiten, sollten Sie die ZIP-Komprimierung verwenden, um zu prüfen, ob sie dieses Limit einhalten. Die Playable-Komprimierung komprimiert diese Dateien nicht noch einmal.

Hinweis: Derzeit werden keine Unity-Projekte unterstützt, die mit der Gzip- oder Brotli-Komprimierung von Unity erstellt wurden. Alle Projekte sollten ohne Komprimierung erstellt werden. Wenn eine Komprimierung erforderlich ist, sollte sie nach dem ersten Build erfolgen.

WebGL-Vorlage

1. Folgen Sie der Anleitung für das Unity-Paket oben, um die anfängliche Einrichtung vorzunehmen. Verwenden Sie Google-WebGLTemplate-only.unitypackage oder GoogleYTGameWrapper-with-sample.unitypackage und importieren Sie alle Dateien im Ordner WebGLTemplates/YTGameWrapperTemplate/.
   • Hinweis: Wenn Sie YTGameWrapper.cs und UnityYTGameSDKLib.jslib noch nicht importiert haben, sollten Sie das jetzt tun.
2. Legen Sie für Ihre WebGL-Vorlage YTGameWrapperTemplate fest. Diese Einstellung finden Sie unter Edit (Bearbeiten) > Project settings (Projekteinstellungen) > Player (Player) > Tab WebGL > Abschnitt Resolution and Presentation (Auflösung und Präsentation).
   • Hinweis: Die Standardbreite und ‑höhe der Canvas sind in der Vorlage auf 100% festgelegt. Diese Unity-Einstellungen haben also keine Auswirkungen.
3. Achten Sie darauf, dass Compression Format (Komprimierungsformat) auf „Disabled“ (Deaktiviert) festgelegt ist. Diese Einstellung finden Sie unter Project settings (Projekteinstellungen) > Player (Player) > Tab WebGL > Abschnitt Publishing Settings (Veröffentlichungseinstellungen).
4. Erstellen Sie im Fenster Build Settings (Build-Einstellungen) einen Build für WebGL und fahren Sie dann je nach Bedarf Ihres Projekts mit Schritt 7 oder 5 fort.
5. Führen Sie die Schritte 5 und 6 nur aus, wenn eine Komprimierung verwendet wird: Nachdem Ihr Projekt erstellt wurde, rufen Sie den Speicherort Ihres Build-Ordners auf und öffnen Sie den Ordner Build. Suchen Sie die .wasm- oder .data-Dateien Ihres Projekts, die komprimiert werden müssen, um die Limits für die individuelle Dateigröße einzuhalten, und komprimieren Sie diese Dateien. Löschen Sie die ursprünglichen .wasm/.data-Dateien, die komprimiert wurden, da Sie stattdessen die Dateien *.wasm.zip und *.data.zip einreichen.
   • Hinweis: Wenn Sie einen Mac verwenden, können Sie mit der rechten Maustaste auf die Datei klicken und „Komprimieren“ auswählen. Auf einem PC können Sie mit der rechten Maustaste auf die Datei klicken und „Komprimieren zu ZIP-Datei“ auswählen.
6. Führen Sie diesen Schritt nur aus, wenn Sie Schritt 5 ausgeführt haben: Aktualisieren Sie die index.html-Datei, die aus YTGameWrapperTemplate erstellt wurde, um ZIP-Dateien zu laden und zu dekomprimieren.
   • Suchen Sie am Ende der index.html-Dateien nach Path 1 und kommentieren Sie die folgende Zeile aus: InitUnitySection();.
   • Suchen Sie am Ende der index.html-Dateien nach Path 2 und kommentieren Sie die folgende Zeile aus: loadResources(InitUnitySection);.
7. Wenn Sie Ihr Projekt zur Zertifizierung einreichen, müssen Sie alle aus Unity erstellten Dateien an den Build-Speicherort aus Schritt 4 senden. Wenn Sie die Schritte 5 und 6 ausgeführt haben, fügen Sie auch diese Dateien hinzu.

Bereitgestellte Beispiele für die Verwendung der Universal Render Pipeline (URP) aktualisieren

Eine der neuesten Entwicklungen bei neueren Versionen von Unity ist die Verwendung der Universal Render Pipeline (URP). So aktualisieren Sie das Beispiel, damit alles korrekt gerendert wird:

1. Importieren Sie zuerst das Paket GoogleYTGameWrapper-with-sample.unitypackage in ein neues oder vorhandenes Projekt.
2. Rufen Sie das Fenster Render Pipeline Converter auf: Window (Fenster) > Rendering (Rendering) > Render Pipeline Converter.
3. Wählen Sie Rendering Settings (Rendering-Einstellungen), Material Upgrade (Material-Upgrade) und Readonly Material Converter (Converter für schreibgeschützte Materialien) aus.
4. Wählen Sie dann Initialize and Convert (Initialisieren und konvertieren) aus. Warten Sie, bis der Vorgang abgeschlossen ist. Das Beispiel sollte jetzt für URP bereit sein.

Assets in Ihrem Unity-Projekt aufteilen (Lazy Loading)

Eines der Hauptprobleme, die Entwickler bei der Verwendung von Unity angesprochen haben, ist die Einhaltung der Anforderungen an die individuelle Dateigröße und die Gesamtgröße des Bundles.

Das Lazy Loading von Assets ist eine gute Optimierung für Ihr Projekt, da Sie Assets, Levels und Daten nach Bedarf laden können. Unser Zertifizierungsteam verzichtet möglicherweise auf die Beschränkungen der Gesamtdateigröße, wenn dies ordnungsgemäß erfolgt, da Ihr vollständiges Spiel nicht im Voraus geladen wird, sondern erst, wenn ein Nutzer Ihr Produkt verwendet.

Um das ordnungsgemäße Laden zu erleichtern, bietet Unity verschiedene Möglichkeiten, Ihre Assets aufzuteilen. So können Sie prüfen, ob Ihre einzelnen Asset-Gruppen die Größenlimits einhalten und dass Inhalte im Laufe der Zeit geladen werden. Wir empfehlen, entweder Addressables oder Asset-Bundles zu verwenden.

Addressables

Mit Addressables können Sie verschiedene Dateien identifizieren, die zusammen geladen werden sollen. Unity übernimmt dann den Großteil der Paketierung für Sie. Unity bietet auch einige Tools zum Verwalten von Dateigrößen und zum Vermeiden von doppelten Assets.

Wenn Sie Addressables verwenden möchten, müssen Sie das Addressables-Paket über den Package Manager in Unity importieren und dann Ihre Assets in Addressable Groups taggen. Weitere Informationen finden Sie in der Unity-Dokumentation.

Asset-Bundles

Asset-Bundles sind hilfreich, da Sie Ihr Projekt aufteilen und Elemente spontan laden können. Sie sind nützlich für DLCs, Level-Pakete, neue Charaktere und mehr. Asset-Bundles eignen sich hervorragend für das selbstverwaltete Laden und Bündeln von Inhalten. Sie können verwendet werden, indem Sie Ihre Assets in bestimmten Bundles taggen und dann Bundles nach Bedarf laden. Weitere Informationen finden Sie in der Unity-Dokumentation zu Asset-Bundles.

Vollständige YT Playables API-Referenz