מתחילים להשתמש ב-Play Games Services ל-Android

זהירות: המדריך הזה מיועד לשימוש ב-Play Games Services v1 SDK. למידע על ה-SDK העדכני ביותר, אפשר לעיין בתיעוד של Play Games Service v2.

ברוך בואך לפיתוח משחקים ל-Android באמצעות שירותי המשחקים של Google Play!

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

הדרכה זו תנחה אתכם להתקין אפליקציה לדוגמה של משחק עבור Android, ולהתחיל במהירות ליצור משחק Android משלכם. האפליקציה לדוגמה של אתגר Type-a-Number מדגימה איך אפשר לשלב הישגים ו-Leaderboards במשחק.

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

כדי להכין את האפליקציה שלך, בצע את השלבים המפורטים בקטעים הבאים.

דרישות מוקדמות לאפליקציה

יש לוודא שקובץ ה-build של האפליקציה משתמש בערכים הבאים:

• minSdkVersion של 19 גבוה יותר
• compileSdkVersion של 28 ומעלה

הגדרת המשחק ב-Google Play Console

ב-Google Play Console מנהלים את שירותי המשחקים של Google Play עבור המשחק ומגדירים מטא-נתונים לאישור המשחק ולאימות שלו. למידע נוסף, ראו הגדרת Google Play Games Services.

הגדרת האפליקציה

בקובץ build.gradle ברמת הפרויקט, יש לכלול את מאגר Maven של Google ואת המאגר המרכזי של Maven בקטע buildscript וגם בקטע allprojects:

  buildscript {
    repositories {
      google()
      mavenCentral()
    }
  }

  allprojects {
    repositories {
      google()
      mavenCentral()
    }
  }

מוסיפים את התלות של Google Play Services של Play Games SDK לקובץ ה-build של Gradle של המודול, לרוב: app/build.gradle:

  dependencies {
    implementation 'com.google.android.gms:play-services-games:23.1.0'
  }

מדריך יישום לדוגמה

הדרכה זו תנחה אתכם להתקין אפליקציית משחק לדוגמה עבור Android ולהתחיל במהירות ליצור משחק Android משלכם. האפליקציה לדוגמה של אתגר Type-a-Number מדגימה איך אפשר לשלב הישגים ו-Leaderboards במשחק.

שלב 1: מורידים את האפליקציה לדוגמה

לקבלת המדריך למפתחים, תצטרכו להוריד את הדוגמה של 'אתגר סוג מספר' ל-Android.

כדי להוריד ולהגדיר את האפליקציה לדוגמה ב-Android Studio:

1. מורידים את הדוגמאות ל-Android מהדף להורדת דוגמאות.
2. מייבאים את הפרויקט android-basic-samples. הפרויקט הזה כולל את TypeANumber ודוגמאות נוספות של משחקים ל-Android. כדי לעשות זאת ב-Android Studio:
   1. לוחצים על קובץ > ייבוא פרויקט.
   2. עוברים לספרייה שאליה הורדתם את android-basic-samples במכונת הפיתוח. בוחרים את הקובץ android-basic-samples/build.gradle ולוחצים על אישור.
3. במודול TypeANumber, פותחים את AndroidManifest.xml ומשנים את שם החבילה מ-com.google.example.games.tanc לשם חבילה אחר משלכם. שם החבילה החדש לא יכול להתחיל ב-com.google, ב-com.example או ב-com.android.

שלב 2: מגדירים את המשחק ב-Google Play Console

ב-Google Play Console מנהלים את שירותי המשחקים של Google Play עבור המשחק ומגדירים מטא-נתונים לאישור המשחק ולאימות שלו.

כדי להגדיר את המשחק לדוגמה ב-Google Play Console:

1. מכוונים את דפדפן האינטרנט אל Google Play Console ונכנסים לחשבון. אם עוד לא נרשמתם ל-Google Play Console, תתבקשו לעשות זאת.
2. פועלים לפי ההוראות הבאות כדי להוסיף את המשחק ל-Google Play Console.
   1. כשמוצגת השאלה אם אתם משתמשים ב-Google APIs באפליקציה, צריך לבחור באפשרות עדיין לא השתמשתי ב-Google APIs במשחק שלי.
   2. למטרת המדריך הזה למפתחים, תוכלו למלא את הטופס בפרטי המשחק שלכם. לנוחיותכם, תוכלו להשתמש בסמלי ה-placeholder ובצילומי המסך שמופיעים בדף Downloads.
3. כדי ליצור מזהה לקוח OAuth 2.0 לאפליקציה ל-Android, צריך לבצע את ההוראות הבאות.
   1. כשמקשרים את האפליקציה ל-Android, חשוב לציין את שם החבילה המדויק שבו השתמשתם מקודם כשמשנים את השם של החבילה לדוגמה.
   2. אם עדיין אין לכם מאגר מפתחות חדש ואישור חתום, תוכלו להשתמש באשף יצירת APK חתום ב-Android Studio. במאמר חתימה על האפליקציה ב-Android Studio מוסבר איך להריץ את האשף 'יצירת APK חתום'.
4. חשוב לתעד את הפרטים הבאים למועד מאוחר יותר:
   1. מזהה האפליקציה: זו מחרוזת שכוללת רק ספרות (בדרך כלל 12 או יותר) בתחילת מזהה הלקוח.
   2. אישור החתימה שלך: שימו לב באיזה אישור השתמשתם כשהגדרתם את הגישה ל-API (האישור שאתם סיפקתם את טביעת האצבע שלו). צריך להשתמש באותו אישור כדי לחתום על האפליקציה במהלך הבדיקה או הפרסום שלה.
5. מגדירים הישגים לאתגר סוג מספר:
   1. בוחרים בכרטיסייה הישגים ב-Google Play Console.
   2. הוסיפו את ההישגים הבאים לדוגמה:

      שם	תיאור	הוראות מיוחדות
      Prime	מקבלים ניקוד שהוא מספר ראשוני.	ללא
      Humble	מבקשים ציון 0.	ללא
      אל תתרגש, ילד	בקש ציון של 9,999 בכל אחד מהמצבים.	ללא
      וואו!	ניתן לקבל ציון של 1337.	כדאי להפוך את זה להישג נסתר.
      משועמם	משחקים 10 פעמים במשחק.	אפשר להפוך את זה להישג מצטבר עם 10 שלבים לשחרור.
      ממש משועמם	משחקים במשחק 100 פעמים.	אפשר להפוך את זה להישג מצטבר עם 100 שלבים כדי לבטל את הנעילה.

   3. צריך לתעד את המזהים (מחרוזות אלפאנומריות ארוכות) לכל הישג שיצרתם.
   4. אפשר להגדיר הישגים שמתאימים למשחק שלך. למידע נוסף, ראו מושגים שמאחורי הישגים ואיך ליישם הישגים ב-Android.
6. מגדירים את לוחות הלידרבורד לאתגר מסוג מספר א:
   1. בוחרים בכרטיסייה לוחות לידרבורד ב-Google Play Console.
   2. מומלץ להוסיף שתי רשימות לידרבורד לדוגמה: אחת בשם 'תוצאות גבוהות בקלות' והשנייה עם השם 'ציון גבוה'. בשתי ה-Leaderboards צריך להשתמש בפורמט ניקוד שלם עם 0 ספרות אחרי הנקודה העשרונית, ובשיטת הסדר גדול יותר טוב.
   3. מתעדים את המזהים (מחרוזות אלפאנומריות ארוכות) של כל לידרבורד שיצרתם.
   4. אפשר להגדיר לוחות לידרבורד שמתאימים למשחק שלך. למידע נוסף, ראו קונספטים מאחורי לוחות לידרבורד ואיך להטמיע לוחות לידרבורד ב-Android.
7. איך מוסיפים חשבונות בדיקה למשחק השלב הזה נדרש רק לאפליקציות שעדיין לא פורסמו ב-Google Play Console. לפני פרסום האפליקציה, אפשר להתחבר רק לחשבונות הבדיקה שרשומים ב-Google Play Console. עם זאת, אחרי פרסום אפליקציה, כולם יכולים להתחבר.

אזהרה: אם תנסו לבצע קריאות ל-Play Games SDK עבור משחק שלא פורסם באמצעות חשבון שלא רשום כחשבון בדיקה, שירותי Google Play Games יפעלו כאילו המשחק לא היה קיים ותקבלו בחזרה את קוד ההחזרה של ConnectionResult.SIGN_IN_REQUIRED. אם תנסו להפעיל את ConnectionResult.startResolutionForResult(), תקבלו חזרה GamesActivityResultCodes.RESULT_SIGN_IN_FAILED.

שלב 3: משנים את הקוד

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

1. פותחים את res/values/ids.xml ומחליפים את מזהי ה-placeholder. אם אתם יוצרים משחק Android מאפס, תחילה עליכם ליצור את הקובץ הזה.
   1. צריך לציין את מזהה האפליקציה במשאב app_id.
   2. מציינים כל מזהה הישג שיצרתם קודם לכן במשאב achievement_* המתאים.
   3. מציינים כל מזהה לידרבורד שיצרתם קודם לכן במשאב leaderboard_* המתאים.
2. פותחים את AndroidManifest.xml ומזינים את שם החבילה במאפיין package של הרכיב <manifest>. אם אתם יוצרים משחק Android מ-Satch, חשוב להוסיף גם את הקוד הבא לרכיב <application>:

   <meta-data android:name="com.google.android.gms.games.APP_ID"
       android:value="@string/app_id" />
   <meta-data android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version"/>
   

שלב 4: בודקים את המשחק

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

הערה: מומלץ לבצע את הבדיקה במכשיר Android פיזי. עם זאת, אם אין לכם מכשיר פיזי, אפשר לבצע בדיקה באמצעות Android Emulator. כדי לעשות זאת, צריך להוריד ממנהל ה-SDK את תמונת המערכת של האמולטור שכוללת את Google Play Services, בקטע Android 4.2.2.

כדי להריץ את המשחק במכשיר הבדיקה הפיזית:

1. מוודאים שהגדרתם את חשבון הבדיקה שבו אתם משתמשים כדי להתחבר לאפליקציה (כפי שמתואר בשלב 2).
2. מייצאים APK וחותמים עליו עם אותו אישור ששימש להגדרת הפרויקט ב-Google Play Console. כדי לייצא APK חתום ב-Android Studio, לוחצים על Build > Generate Signed APK (יצירת APK חתום).
3. יש להתקין את ה-APK החתום במכשיר הבדיקה הפיזית באמצעות הכלי adb. במאמר ריצה במכשיר מוסבר איך מתקינים אפליקציה.

אזהרה: כשמריצים את האפליקציה ישירות מ-Android Studio, מערכת Android Studio תחתום על האפליקציה עם אישור ניפוי הבאגים כברירת מחדל. אם לא השתמשתם באישור ניפוי הבאגים הזה כשהגדרתם את האפליקציה ב-Google Play Console, הדבר יגרום לשגיאות. חשוב להקפיד להריץ APK שייצאתם וחתמתם עליו עם אישור שתואם לאחד מהאישורים שבהם השתמשתם כשהגדרתם את האפליקציה ב-Google Play Console.