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

בעקבות הוצאה משימוש של Google Sign-In API, אנחנו מסירים את ה-SDK בגרסה Games v1 בשנת 2026. אחרי פברואר 2025, לא תהיה לך אפשרות לפרסם ב-Google Play משחקים ששולבו לאחרונה עם ה-SDK בגרסה Games v1. מומלץ להשתמש ב-SDK בגרסה Games v2.
משחקים קיימים עם שילובים קודמים של Games v1 ימשיכו לפעול למשך כמה שנים, אבל מומלץ לעבור לגרסה 2 החל מיוני 2025.
המדריך הזה מיועד לשימוש ב-Play Games Services SDK בגרסה 1. מידע על גרסת ה-SDK העדכנית זמין במאמרי העזרה בנושא גרסה 2.

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

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

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

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

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

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

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

• minSdkVersion מתוך 19 או יותר
• compileSdkVersion מתוך 28 או יותר

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

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

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

בקובץ 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.2.0'
  }

מדריך לאפליקציה לדוגמה

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

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

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

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

1. מורידים את הדוגמאות ל-Android מדף ההורדות של הדוגמאות.
2. מייבאים את הפרויקט android-basic-samples. הפרויקט הזה כולל את TypeANumber ודוגמאות נוספות למשחקי Android. כדי לעשות את זה ב-Android Studio:
   1. לוחצים על File (קובץ) > Import Project (ייבוא פרויקט).
   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 Games Services למשחק שלכם ולהגדיר מטא-נתונים לצורך הרשאה ואימות של המשחק.

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

1. פותחים את דפדפן האינטרנט ומזינים את כתובת האתר של Google Play Console, ואז נכנסים לחשבון. אם עדיין לא נרשמתם ל-Google Play Console, תתבקשו לעשות זאת.
2. פועלים לפי ההוראות האלה כדי להוסיף את המשחק ל-Google Play Console.
   1. כשנשאלים אם נעשה שימוש ב-Google APIs באפליקציה, בוחרים באפשרות I don’t use any Google APIs in my game yet (עדיין לא נעשה שימוש ב-Google APIs במשחק שלי).
   2. לצורך מדריך המפתחים הזה, אפשר למלא את הטופס בפרטים של המשחק שלכם. לנוחיותכם, תוכלו להשתמש בסמלי placeholder ובצילומי המסך שמופיעים בדף הורדות.
3. כדי ליצור מזהה לקוח OAuth 2.0 לאפליקציית Android, צריך לפעול לפי ההוראות הבאות.
   1. כשמקשרים את אפליקציית Android, חשוב לציין את שם החבילה המדויק שבו השתמשתם קודם כששיניתם את השם של חבילת הדוגמה.
   2. אם אין לכם חתימה, אתם יכולים להשתמש באשף Generate Signed APK (יצירת קובץ APK חתום) ב-Android Studio כדי ליצור מאגר מפתחות חדש ואישור חתום. כאן מוסבר איך מריצים את האשף ליצירת APK חתום.
4. חשוב לתעד את הפרטים הבאים לשימוש בהמשך:
   1. מזהה הבקשה: מחרוזת שמורכבת רק מספרות (בדרך כלל 12 או יותר), בתחילת מזהה הלקוח.
   2. אישור החתימה: חשוב לשים לב באיזה אישור השתמשתם כשקבעתם את גישת ה-API (האישור שטביעת האצבע שלו ב-SHA1 סופקה). כדאי להשתמש באותו אישור לחתימה על האפליקציה כשבודקים אותה או מפרסמים אותה.
5. הגדרת הישגים לאתגר 'הקלדת מספרים':
   1. לוחצים על הכרטיסייה הישגים ב-Google Play Console.
   2. מוסיפים את ההישגים לדוגמה הבאים:

      שם	תיאור	הוראות מיוחדות
      Prime	להשיג ניקוד שהוא מספר ראשוני.	ללא
      ענוו	מבקשים ניקוד של 0.	ללא
      אל תהיה בטוח בעצמך מדי, ילד	לבקש ציון של 9999 בכל אחד מהמצבים.	ללא
      OMG U R TEH UBER LEET!	קבלת ציון של 1337.	הגדרת ההישג הזה כהישג מוסתר.
      משעמם	משחקים במשחק 10 פעמים.	הגדרת ההישג הזה כהישג מצטבר עם 10 שלבים לביטול הנעילה.
      ממש משעמם	משחקים במשחק 100 פעמים.	הגדרת ההישג הזה כהישג מצטבר עם 100 שלבים לביטול הנעילה.

   3. צריך לתעד את המזהים (מחרוזות אלפאנומריות ארוכות) של כל הישג שיצרתם.
   4. הגדרת הישגים שמתאימים למשחק שלכם. מידע נוסף זמין במאמרים הסברים על ההישגים ואיך מטמיעים הישגים ב-Android.
6. מגדירים את לוחות הלידרבורד עבור האתגר 'הקלדת מספרים':
   1. לוחצים על הכרטיסייה טבלאות הישגים ב-Google Play Console.
   2. מוסיפים שני לוחות לידרבורד לדוגמה: אחד בשם Easy High Scores (התוצאות הגבוהות ברמה קלה) ואחד בשם Hard High Scores (התוצאות הגבוהות ברמה קשה). בשני לוחות הלידרבורד צריך להשתמש בפורמט של מספרים שלמים עם 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 ומחליפים את מזהי הפלייסהולדר. אם אתם יוצרים משחק ל-Android מאפס, תצטרכו ליצור את הקובץ הזה קודם.
   1. מציינים את מזהה האפליקציה במשאב app_id.
   2. מציינים כל מזהה הישג שיצרתם קודם במשאב achievement_* המתאים.
   3. מציינים כל מזהה של טבלת הישגים שיצרתם קודם במשאב leaderboard_* המתאים.
2. פותחים את AndroidManifest.xml ומזינים את שם החבילה במאפיין package של הרכיב <manifest>. אם אתם יוצרים משחק ל-Android מאפס, הקפידו להוסיף את הקוד הבא בתוך האלמנט <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 פועלים בצורה תקינה במשחק, צריך לבדוק את האפליקציה לפני שמפרסמים אותה ב-Google Play.

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

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

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.