wrapper ניסיוני של YouTube במשחקייה

באמצעות העטיפה הזו אפשר לגשת אל SDK המשחקייה של YouTube ב-Unity C#. ה-wrapper כולל תוסף ‎ .jslib וקובץ C# ‎ כדי לעזור לכם לפתח מהר יותר. יש גם פרויקט לדוגמה שמראה איך אפשר להשתמש בהם בפרויקט שלכם.

אפשר להוריד חבילות Unity ממאגר הדוגמאות של Playables.

שימוש

  1. מוודאים שהפלטפורמה של פרויקט Unity מוגדרת ל-WebGL. ההגדרה הזו נמצאת בBuild Settings.
  2. אפשר להשתמש ב-WebGLTemplate כדי ליצור את המשחק לאינטרנט, או לפעול לפי ההוראות שבקטע שימוש בקובץ index.html משלכם ולוודא שהגדרתם והפעלתם את web SDK בקובץ index.html.
    • ‫WebGLTemplate נמצא בחבילה Google-WebGLTemplate-only.unitypackage או GoogleYTGameWrapper-with-sample.unitypackage. כדי להגדיר את התבנית הזו ולהשתמש בה, צריך לפעול לפי השלבים שבקטע תבנית WebGL.
    • כדי להשתמש בקובץ index.html משלכם, צריך להוסיף שתי שורות לסקריפט היצירה של index.html Unity. פרטים נוספים זמינים בקטע שימוש בקובץ index.html משלכם.
  3. פותחים את הפרויקט ב-Unity, ואז פותחים ומייבאים את אחת מהחבילות לפרויקט.
    • ‫GoogleYTGameWrapper.unitypackage: מכיל פלאגין JS לחיבור של ה-SDK של המשחקייה של YouTube ועטיפת C# ‎ כדי לעזור לכם לחבר את זה למוצר שלכם.
    • ‫GoogleYTGameWrapper-with-sample.unitypackage: מכיל את אותם קבצים ותוכן כמו אלה שנמצאים בחבילה GoogleYTGameWrapper, ודוגמה שמראה איך להשתמש ב-SDK של המשחקייה של YouTube ב-C#.
  4. חשוב: בסצנה הראשית, יוצרים אובייקט משחק חדש ונותנים לו את השם YTGameWrapper. אובייקט המשחק הזה משמש לתקשורת עם גשר ה-JS.
  5. חשוב: מוסיפים את קוד YTGameWrapper.cs המיובא כרכיב סקריפט לאובייקט YTGameWrapper GameObject.

  6. אם לפרויקט יש כמה סצנות, צריך להוסיף DontDestroyOnLoad לסקריפט YTGameWrapper.cs (הערה: בגרסאות חדשות של הסקריפט יש מתג DontDestroyOnSceneChange שמופעל כברירת מחדל). כך מוודאים שהסקריפט ו-GameObject יישארו לאורך כל המשחק.

    GameObject.DontDestroyOnLoad(this.gameObject);

  7. רכיב YTGameWrapper.cs ואובייקט YTGameWrapper GameObject משמשים לחיבור אל YouTube Playables SDK. אפשר להשתמש בהם כדי להתחבר אל YouTube. אפשר להשתמש בסקריפט כדי למצוא את האובייקט והרכיב, או להוסיף אותם באופן ידני לקוד המשחק באמצעות Unity Editor.

  8. מוודאים שאתם פועלים בהתאם לדרישות הטכניות של הפרויקט.

שימוש בקובץ index.html משלכם

אם לא משתמשים בדוגמה שמופיעה בקטע index.html, צריך להוסיף שני קטעי קוד לסקריפט היצירה של index.html Unity.

קודם כול, מוסיפים את השורה הזו באותו מקום שבו הפרויקט מגדיר משתנים עבור מאגר Unity, בד, וכו'.

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

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

    ...

שנית, מוסיפים את השורה הזו בתוך הפונקציה createUnityInstance.

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

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

    ...

דוגמאות

בקטע הזה מופיעות כמה דוגמאות לשימוש ב-wrapper של C# ‎, אבל זו לא רשימה מלאה של ממשקי ה-API הזמינים. רשימה מלאה של ממשקי ה-API הזמינים מופיעה ב-YouTube Playables SDK.

sendScore

בדוגמה הזו מוצגת הטמעה של sendScore(int points) ב-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

זוהי דוגמה לאופן שבו משחק יכול להאזין לאירועים מסוג Pause שמגיעים מ-YT Playables, כדי להשהות את המנוע שלו כשצריך:

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

זו דוגמה לאופן השימוש ב-saveData, ושליחתו אל YT Playables SDK:

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

זו דוגמה לאופן השימוש ב-loadData, ושליחתו אל YT Playables SDK:

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

זו דוגמה לשימוש ב-requestInterstitialAd, שמציינת שזה זמן טוב להציג מודעת מעברון, אם יש כזו. כדי להשיג את התוצאות הטובות ביותר, כדאי לבצע את הקריאה הזו במהלך הפסקה במשחק, למשל בסיום שלב.

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

זו דוגמה לשימוש ב-requestRewardedAd. משתמשים בה כשמשתמש בוחר לצפות במודעה מתגמלת בתמורה לתגמול כלשהו במשחק. אם יש מודעה זמינה, היא תוצג למשתמש.

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

איך משתמשים בתבנית WebGL לדוגמה של YouTube

אלא אם יש לכם פרויקט Unity גדול מאוד, הקבצים .wasm ו-.data שנוצרו צריכים להיות קטנים ממגבלת גודל הקובץ הבודד שלנו. אם זה המצב, לא צריך לבצע דחיסה נוספת בקבצים האלה, כי הם יידחסו אוטומטית כששולחים את הקבצים האינטראקטיביים. הדחיסה האוטומטית הזו גם תאמת שהקובץ ‎ .wasm עומד בדרישה של גודל החבילה הראשוני. לדוגמה, קובץ .wasm בגודל של ‎~25 MiB יידחס לגודל של ‎~7 MiB.

אם מסיבה כלשהי הקבצים שלכם חורגים ממגבלת הגודל המקסימלית של קובץ בודד, מומלץ להשתמש בדחיסת ZIP כדי לוודא שהם עומדים במגבלה הזו. הדחיסה שמאפשרת הפעלה לא תדחס מחדש את הקבצים האלה.

תבנית WebGL

  1. פועלים לפי ההוראות להגדרת חבילת Unity שמופיעות למעלה כדי לבצע את ההגדרה הראשונית. חשוב להשתמש ב-Google-WebGLTemplate-only.unitypackage או ב-GoogleYTGameWrapper-with-sample.unitypackage ולייבא את כל הקבצים בתיקייה WebGLTemplates/YTGameWrapperTemplate/.
    • הערה: אם עדיין לא ייבאתם את YTGameWrapper.cs ו-UnityYTGameSDKLib.jslib, כדאי לייבא גם אותם.
  2. מגדירים את תבנית WebGL לשימוש ב-YTGameWrapperTemplate. ההגדרה הזו נמצאת בEdit -> Project settings -> Player -> הכרטיסייה WebGL -> הקטע Resolution and Presentation.
    • הערה: רוחב וגובה ברירת המחדל של Canvas מוגדרים ל-100% בתבנית, כך שההגדרות האלה ב-Unity לא ישנו שום דבר.
  3. מוודאים שההגדרה Compression Format מושבתת. ההגדרה הזו נמצאת בProject settings -> Player -> הכרטיסייה WebGL -> הקטע Publishing Settings.
  4. בונים את WebGL בחלון Build Settings ואז עוברים לשלב 7 או 5 בהתאם לצרכים של הפרויקט.
  5. צריך לבצע רק את שלבים 5 ו-6 אם משתמשים בדחיסה: אחרי שיוצרים את הפרויקט, עוברים למיקום של תיקיית ה-build ופותחים את התיקייה Build. מאתרים את הקבצים .wasm או .data של הפרויקט שצריך לדחוס כדי שהם יעמדו במגבלות גודל הקובץ, ודוחסים אותם לקובץ ZIP. חשוב למחוק את הקבצים המקוריים .wasm או .data שנדחסו, כי אתם תשלחו במקומם את הקבצים *.wasm.zip ו-*.data.zip.
    • הערה: אם אתם משתמשים ב-Mac, אתם יכולים ללחוץ לחיצה ימנית על הקובץ ולבחור באפשרות 'דחיסת *'. במחשב, אתם יכולים ללחוץ לחיצה ימנית על הקובץ ולבחור באפשרות 'דחיסה לקובץ ZIP'.
  6. רק אם ביצעתם את שלב 5: מעדכנים את קובץ index.html שנבנה מ-YTGameWrapperTemplate כדי לטעון קבצים דחוסים ולחלץ אותם.
    • לקראת סוף הקבצים index.html, מאתרים את Path 1 ומעבירים את השורה הבאה InitUnitySection(); להערה.
    • לקראת סוף הקבצים index.html, מוצאים את Path 2 ומסמנים את השורה הבאה כהערה loadResources(InitUnitySection);.
  7. כששולחים את הפרויקט לאישור, צריך לשלוח את כל הקבצים שנוצרו מ-Unity למיקום הבנייה משלב 4. אם ביצעתם את שלבים 5 ו-6, צריך לכלול גם את הקבצים האלה.

שדרוג הדוגמאות שסופקו לשימוש ב-Universal Render Pipeline ‏ (URP)

אחד מהחידושים האחרונים בגרסאות חדשות יותר של Unity הוא השימוש ב-Universal Render Pipeline ‏ (URP). כדי לשדרג את הדוגמה כך שהכול יעבור רינדור בצורה נכונה,

  1. כדי להתחיל, מייבאים את חבילת GoogleYTGameWrapper-with-sample.unitypackage ההתקנה לפרויקט חדש או קיים.
  2. עוברים לחלון Render Pipeline Converter: Window -> Rendering -> Render Pipeline Converter.
  3. בוחרים באפשרות Rendering Settings, Material Upgrade ו-Readonly Material Converter.
  4. לאחר מכן בוחרים באפשרות Initialize and Convert, מחכים לסיום התהליך והדוגמה אמורה להיות מוכנה ל-URP.

איך מפצלים נכסים בפרויקט Unity (טעינה עצלה)

אחת הבעיות העיקריות שמפתחים מציינים בשימוש ב-Unity היא שמירה על דרישות גודל הקובץ הבודד ועל דרישות גודל החבילה הכולל.

טעינה עצלה של נכסים היא אופטימיזציה מצוינת שאפשר לבצע בפרויקט, כי אפשר לטעון נכסים, רמות ונתונים לפי הצורך. צוות האישורים שלנו עשוי לוותר על ההגבלות על גודל הקובץ הכולל אם הטעינה העצלה מבוצעת בצורה נכונה, כי המשחק המלא לא ייטען מראש, אלא בזמן שהמשתמש עובר בין חלקי המוצר.

כדי לעזור לכם לטעון את הנכסים בצורה נכונה, ב-Unity יש כמה דרכים לפצל את הנכסים. כך תוכלו לוודא שקבוצות הנכסים הבודדות לא חורגות ממגבלות הגודל, ושהתוכן נטען לאורך זמן. מומלץ להשתמש ב-Addressables או ב-Asset Bundles.

כתובות שאפשר לשלוח אליהן

התכונה Addressables מאפשרת לכם לזהות קבצים שצריך לטעון יחד, ו-Unity מטפלת ברוב האריזה בשבילכם. בנוסף, Unity מספקת כמה כלים לניהול גודל הקבצים, כדי לוודא שלא משכפלים נכסים.

כדי להשתמש ב-Addressables, צריך לייבא את חבילת Addressables דרך Package Manager ב-Unity, ואז לתייג את הנכסים ב-Addressable Groups. אפשר למצוא פרטים נוספים בתיעוד של Unity.

חבילות App Bundle של נכסים

חבילות נכסים שימושיות כי אפשר לפצל את הפרויקט ולטעון רכיבים תוך כדי תנועה. הם שימושיים לתוכן להורדה (DLC), לחבילות של רמות, לדמויות חדשות ועוד. חבילות נכסים הן פתרון מצוין לטעינה ולאריזה של תוכן בניהול עצמי. אפשר להשתמש בהם על ידי תיוג הנכסים בחבילות ספציפיות, ואז טעינת החבילות לפי הצורך. פרטים נוספים זמינים במאמרי העזרה של Unity בנושא חבילות נכסים.

הפניית YT Playables API