איך מתחילים לעבוד עם הפלאגין של Google Play Games ל-Unity

בנושא הזה מוסבר איך להגדיר את הפרויקט ב-Unity כך שישתמש בפלאגין של Google Play Games ל-Unity. המשימות כוללות הגדרת הפרויקט, בחירת פלטפורמה של רשת חברתית והגדרת כניסה של שחקנים.

לפני שמתחילים

התקנת יישומי פלאגין

  1. אפשר לקבל את הפלאגין באחת מהדרכים הבאות:

  2. מוצאים את הקובץ unitypackage בספרייה current-build. זהו הקובץ של הפלאגין. לדוגמה, הוא אמור להיראות כך:

      current-build/GooglePlayGamesPluginForUnity-X.YY.ZZ.unitypackage
    
  3. פותחים את פרויקט המשחק ב-Unity.

  4. כדי לייבא את הקובץ unitypackage לנכסים של הפרויקט, לוחצים על האפשרות Assets > Import Package > Custom Package בתפריט.

  5. מוודאים שפלטפורמת ה-build הנוכחית מוגדרת ל-Android.

    1. בתפריט הראשי, לוחצים על File > Build Settings… (קובץ > הגדרות build…).

    2. בוחרים באפשרות Android ולוחצים על Switch Platform (החלפת פלטפורמה).

    3. אמור להופיע פריט תפריט חדש בקטע חלון > Google Play Games. אם אין שם, מרעננים את הנכסים בלחיצה על Assets > Refresh ולאחר מכן מנסים להגדיר את פלטפורמת ה-build שוב.

איך מקבלים משאבים ל-Android מ-Play Console

כל הישג, לוח מנהיגים ואירוע שיוצרים ב-Play Console כוללים משאב ל-Android שמשמש להגדרת פרויקט Unity.

  1. מקבלים את המשאבים של Android למשחק.

    1. ב-Play Console, פותחים את הפרויקט של Play Games Services למשחק.

    2. לוחצים על הכרטיסייה Achievements (הישגים) ואז על Get resources (קבלת משאבים).

    3. בחלון ייצוא משאבים, לוחצים על הכרטיסייה Android.

    4. בוחרים את תוכן ה-XML ומעתיקים אותו.

הגדרת הפרויקט ב-Unity

  1. מוסיפים את המשאבים של Android לפרויקט ב-Unity.

    1. ב-Unity, לוחצים על ** Window (חלון) > Google Play Games (משחקי Google Play) > Setup (הגדרה)... > הגדרת Android **.

    2. ממלאים את הפרטים הבאים בחלונות ההגדרה:

    3. ספרייה לשמירת קבועים: התיקייה של קובץ הקבועים.

    4. Constants class name: השם של מחלקת C# שיוצרים, כולל מרחב השמות.

    5. הגדרת משאבים: מדביקים כאן את נתוני המשאבים של Android מ-Play Console.

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

    7. לוחצים על Setup (הגדרה). הפעולה הזו מגדירה את המשחק עם מזהה הלקוח ויוצרת כיתה ב-C# שמכילה קבועים לכל אחד מהמשאבים של Android.

הגדרת Android

מגדירים את הנתיב להתקנה של Android SDK ב-Unity. הוא נמצא בתפריט ההעדפות, בקטע External Tools (כלים חיצוניים).

כדי להגדיר שהמשחק שלכם ב-Unity יפעל עם Google Play Games ב-Android, פותחים קודם את מנהל ה-SDK של Android ומוודאים שהורדתם את החבילות הבאות. שמות הרכיבים עשויים להשתנות אם אתם משתמשים במנהל ה-SDK מ-Android Studio או במנהל ה-SDK העצמאי. - Google Play Services - Android Support Library - מאגר מקומי של Maven לספריות תמיכה (נקרא גם Android Support Repository) - מאגר Google - Android 6.0‏ (API 23) (הדבר לא משפיע על גרסת ה-SDK המינימלית).

בשלב הבא מגדירים את שם החבילה של המשחק. לשם כך, לוחצים על File > Build Settings, בוחרים את פלטפורמת Android ולוחצים על Player Settings כדי להציג את חלון הגדרות הנגן של Unity. בחלון הזה, מחפשים את ההגדרה מזהה החבילה בקטע הגדרות אחרות. מזינים שם חבילה (לדוגמה, com.example.my.awesome.game).

כדי להיכנס ל-Play Game Services, צריך לחתום על קובץ ה-APK, הקפידו לחתום עליו באמצעות האישור הנכון, כלומר זה שתואם למאפיין האצבע של אישור ה-SHA1 שהזנתם במסוף הפיתוח במהלך ההגדרה.

לאחר מכן, לוחצים על אפשרות התפריט חלון |Google Play Games|הגדרה – הגדרת Android. יוצג מסך ההגדרה של Android.

מזינים את שם הכיתה Constants. זהו השם של הכיתה המלאה שתעודכן (או תיווצר) ותכיל את המזהים של משאבי המשחק. הפורמט של השם הוא <namespace>.<classname>. לדוגמה, AwesomeGame.GPGSIds

מדביקים את נתוני הגדרת המשאב. אלה נתוני ה-XML מ-Google Play Developer Console שמכילים את מזהי המשאבים וגם את מזהה האפליקציה ל-Android.

כדי למצוא את הנתונים האלה ב-Google Play Developer Console, לוחצים על 'קבלת משאבים' בדף כלשהו של משאבים (למשל 'הישגים' או 'לוחות מנהיגות') ואז לוחצים על Android.

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

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

הוראות נוספות לגבי פיתוח ל-Android ב-Windows

אם אתם משתמשים ב-Windows, עליכם לוודא של-Unity יש גישה להתקנה של Java SDK. לשם כך:

  1. מגדירים את משתנה הסביבה JAVA_HOME לנתיב ההתקנה של Java SDK (לדוגמה, C:\Program Files\Java\jdk1.7.0_45).
  2. מוסיפים את התיקייה bin של Java SDK למשתנה הסביבה PATH (לדוגמה, C:\Program Files\Java\jdk1.7.0_45\bin)
  3. הפעלה מחדש.

איך עורכים משתני סביבה: ב-Windows 2000/XP/Vista/7, לוחצים לחיצה ימנית על My Computers ואז על Properties (מאפייני מערכת מתקדמים), ולאחר מכן אל Advanced System Properties (מאפייני מערכת מתקדמים) (או System Properties), ואז לוחצים על הכרטיסייה Advanced), ואז לוחצים על Environment Variables. ב-Windows 8, מקישים על Windows Key + W ומחפשים משתני סביבה. למידע נוסף, אפשר לעיין במאמרי העזרה של גרסת Windows שבה אתם משתמשים.

הפעלת הפרויקט

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

כדי ל-build ולהרצה ב-Android, לוחצים על File > Build Settings, בוחרים את פלטפורמת Android > Switch to Platform > Build and Run.

בחירת פלטפורמה חברתית

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

ניתן לגשת לקריאות הרגילות ל-API דרך האובייקט Social.Active, שהוא הפניה לממשק ISocialPlatform. כדי לגשת לתוספים הלא סטנדרטיים של Google Play Games, צריך להעביר (cast) את האובייקט Social.Active לכיתה PlayGamesPlatform, שבה נמצאות השיטות הנוספות.

שימוש בפלאגין בלי לשנות את פלטפורמת הרשת החברתית שמוגדרת כברירת מחדל

כשאתם קוראים ל-PlayGamesPlatform.Activate, Google Play Games הופכת להטמעה שמוגדרת כברירת מחדל של הפלטפורמה החברתית. כלומר, קריאות סטטיות לשיטות ב-Social וב-Social.Active יבוצעו על ידי הפלאגין של Google Play Games. זו ההתנהגות הרצויה ברוב המשחקים שמשתמשים בפלאגין.

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

  1. אין להתקשר אל PlayGamesPlatform.Activate
  2. אם Xyz הוא שם של שיטה שרוצים להפעיל על המחלקה Social, לא צריך להפעיל את Social.Xyz. במקום זאת, צריך להתקשר אל PlayGamesPlatform.Instance.Xyz
  3. אסור להשתמש ב-Social.Active במהלך אינטראקציה עם Google Play Games. במקום זאת, אתם צריכים להשתמש ב-PlayGamesPlatform.Instance.

כך תוכלו לשלוח ציונים והישגים בו-זמנית לשתי פלטפורמות חברתיות או יותר:

    // Submit achievement to original default social platform
    Social.ReportProgress("MyAchievementIdHere", 100.0f, callback);

    // Submit achievement to Google Play
    PlayGamesPlatform.Instance.ReportProgress("MyGooglePlayAchievementIdHere", 100.0f, callback);

אימות שירות הכניסה

כשפותחים את המשחק, מתבצע ניסיון חיבור אוטומטי לשירותי Play Games באמצעות שירות הכניסה. אם החיבור יצליח, תוצג במשחק הודעת כניסה והוא מוכן לשימוש בפלאגין של Google Play Games ל-Unity.

אם משתמש מעולם לא השתמש ב-Google Play Games במכשיר שלו, הוא מועבר אוטומטית למסך ההגדרה החד-פעמי כדי ליצור חשבון Play Games.

בשיטת Start של הסקריפט, מקשיבים לתוצאה של ניסיון הכניסה האוטומטי, מאחזרים את סטטוס האימות ומשביתים את התכונות של Play Games Services אם המשתמש לא מחובר.

    using GooglePlayGames;

    public void Start() {
      PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);
    }

    internal void ProcessAuthentication(SignInStatus status) {
      if (status == SignInStatus.Success) {
        // Continue with Play Games Services
      } else {
        // Disable your integration with Play Games Services or show a login button
        // to ask users to sign-in. Clicking it should call
        // PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).
      }
    }
}

קוד התוצאה הוא enum שאפשר להשתמש בו כדי לזהות את הסיבה לכישלון הכניסה.

אם אתם מעדיפים להשתמש בפלטפורמה של Unity לניהול רשתות חברתיות, תוכלו להשתמש בקוד הבא:

  using GooglePlayGames;

  public void Start() {
    PlayGamesPlatform.Activate();
    Social.localUser.Authenticate(ProcessAuthentication);
  }

אי אפשר לבצע קריאות ל-Google Play Games API עד שמקבלים ערך חזרה מוצלח מ-Authenticate. לכן, מומלץ להציג במשחקים מסך המתנה עד לקריאה החוזרת, כדי לוודא שהמשתמשים לא יוכלו להתחיל לשחק במשחק עד שהאימות יושלם.

אחזור קודי אימות שרת

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

כדי לקבל את קוד הגישה בצד השרת:

  1. מגדירים את מזהה לקוח האינטרנט של אפליקציית האינטרנט שמקושרת למשחק ב-Play Games Console.

  2. קוראים ל-PlayGamesPlatform.Instance.RequestServerSideAccess אחרי שהשחקן מאומת כדי לקבל את קוד הגישה בצד השרת.

  3. מעבירים את הקוד הזה לאפליקציית השרת.

  PlayGamesPlatform.Instance.RequestServerSideAccess(
    /* forceRefreshToken= */ false,
    code -> {
      // send code to server
    });

הגדרה והוספה של תכונות