הגדרה

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

הפעלת תגובות מ-Play Integrity API

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

הגדרה ב-Google Play Console (מומלץ)

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

הגדרה במסוף Google Cloud

במסוף Google Cloud, יוצרים פרויקט חדש ב-Cloud או בוחרים פרויקט קיים ב-Cloud שבו רוצים להשתמש עם Play Integrity API. עוברים אל APIs and services. בוחרים באפשרות enable APIs and services. מחפשים את Play Integrity API וממפעילים אותו. עכשיו אפשר לשלב את Play Integrity API באפליקציה.

הוראות הגדרה לספקים של SDK

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

למפתחי SDK יש שתי אפשרויות להגדיר את Play Integrity API: Google Play SDK Console או מסוף Google Cloud.

הפעלת התשובות של Play Integrity API במסוף Google Play SDK מאפשרת לכם לקבל גישה לאפשרויות הגדרה נוספות. עוברים אל תקינות ה-SDK ולוחצים על הגדרות. בקטע Project configuration (הגדרת הפרויקט), בוחרים באפשרות Link a Cloud project. בוחרים את פרויקט Cloud שרוצים לקשר ל-SDK, וכך מפעילים את התגובות של Play Integrity API. עכשיו אפשר לשלב את Play Integrity API ב-SDK. חשוב לדעת שהגישה ל-Google Play SDK Console כפופה לקריטריונים לזכאות.

שימוש במסוף Google Cloud

אפשר להפעיל תגובות ל-Play Integrity API דרך מסוף Google Cloud. במסוף Google Cloud, יוצרים פרויקט חדש ב-Cloud או בוחרים פרויקט קיים ב-Cloud שבו רוצים להשתמש עם Play Integrity API. עוברים אל APIs and services. בוחרים באפשרות enable APIs and services. מחפשים את Play Integrity API וממפעילים אותו. עכשיו אפשר לשלב את Play Integrity API ב-SDK.

הגדלת מספר הבקשות היומיות של ה-SDK ל-Play Integrity API

ספקי SDK שרוצים להגדיל את מספר הבקשות היומיות המקסימלי צריכים למלא את טופס הבקשה להגדלת המכסה. בקטע של ההערות הפתוחות, מציינים שמדובר בבקשה ל-SDK ומצרפים את הקואורדינטות של Maven ‏ (groupId:artifactId) או כתובת URL של ה-SDK.

הגדלת מספר הבקשות היומיות ל-Play Integrity API

האפליקציה שלכם תהיה כפופה למגבלה של 10,000 בקשות בסך הכול לכל אפליקציה ביום. אם האפליקציה שלכם צריכה לטפל במספר גדול יותר של משתמשים, תוכלו לבקש להגדיל את המכסה היומית לפי ההוראות שבהמשך.

הגדלת המספר המקסימלי של בקשות יומיות

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

כדי לבקש להגדיל את המספר המקסימלי היומי של הבקשות, צריך לפעול לפי השלבים הבאים:

  1. מקשרים ב-Play Console את הפרויקט ב-Google Cloud שבו אתם משתמשים ב-Play Integrity API.
  2. מוודאים שהטמעתם בצורה נכונה את הלוגיקה של ה-API, כולל האסטרטגיה המומלצת לביצוע ניסיונות חוזרים.
  3. כדי לבקש הגדלה של המכסה, יש למלא את הטופס הזה.

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

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

שילוב של Play Integrity API באפליקציה

כדי לשלב את Play Integrity API באפליקציה או ב-SDK, מבצעים אחת מהפעולות הבאות בהתאם לסביבת הפיתוח:

Kotlin או Java

הספרייה העדכנית ביותר ל-Android עבור Play Integrity API זמינה במאגר Maven של Google. מוסיפים את יחסי התלות הבאים לקובץ build.gradle של האפליקציה:

implementation 'com.google.android.play:integrity:1.4.0'

Unity

מתקינים את Google Play Integrity Plugin for Unity בגרסה 1.3.0 ואילך. הוראות מפורטות זמינות במאמר איך להתקין חבילות של Google ל-Unity.

  • יש תמיכה בכל הגרסאות של 2019.x,‏ 2020.x ואילך.
  • אם אתם משתמשים ב-Unity 2018.x, יש תמיכה בגרסה 2018.4 ואילך.
  • לא ניתן להשתמש ב-Unity 2017.x וגרסאות ישנות יותר.

מותאמת

מתקינים את Play Core Native SDK בגרסה 1.13.0 ואילך. הוראות מפורטות זמינות במדריך להגדרת סביבת הפיתוח של Play Core Native.

הגדרת תגובות API (אופציונלי)

תגובת ה-API כוללת את פסקי הדין שמוגדרים כברירת מחדל ומוחזרים בכל בקשה. אם מגדירים את השילוב של Play Integrity API ב-Play Console, אפשר להתאים אישית את התשובה של ה-API.

תשובות ברירת מחדל

קביעות התקינות הבאות מוחזרות בתגובה של Play Integrity API כברירת מחדל:

שדה התשובה ערך תיאור
תקינות המכשיר MEETS_DEVICE_INTEGRITY האפליקציה פועלת במכשיר Android שמופעל על ידי Google Play Services. המכשיר עובר את בדיקות התקינות של המערכת ועומד בדרישות התאימות של Android.
ריק (ערך ריק) האפליקציה פועלת במכשיר שיש בו סימנים למתקפה (כמו הוק של API) או לפריצה למערכת (כמו התקנת Root), או שהאפליקציה לא פועלת במכשיר פיזי (כמו אמולטור שלא עובר את בדיקות התקינות של Google Play).
פרטי חשבון Play LICENSED למשתמש יש הרשאה לאפליקציה. במילים אחרות, המשתמש התקין או עדכן את האפליקציה שלכם במכשיר שלו מ-Google Play.
UNLICENSED למשתמש אין הרשאה לאפליקציה. המצב הזה קורה, למשל, כשהמשתמש מתקין את האפליקציה בשיטה חלופית או לא מתקין אותה דרך Google Play.
UNEVALUATED פרטי הרישוי לא נבדקו כי לא בוצעה עמידה בדרישה. יכולות להיות לכך כמה סיבות, כולל:
  • המכשיר לא מהימן מספיק.
  • המשתמש לא מחובר ל-Google Play.
  • גרסת האפליקציה שמותקנת במכשיר לא ידועה ל-Google Play.
מהימנות אפליקציה PLAY_RECOGNIZED האפליקציה והאישור תואמים לגרסאות שמופצות על ידי Google Play.
UNRECOGNIZED_VERSION שם האישור או החבילה לא תואם לרשומות ב-Google Play.
UNEVALUATED לא בוצעה הערכה של תקינות האפליקציה. לא בוצעה עמידה בדרישה נדרשת, למשל המכשיר לא מהימן מספיק.

תשובות מותנות

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

שדה התשובה תווית תיאור
תקינות המכשיר MEETS_VIRTUAL_INTEGRITY האפליקציה פועלת באמולטור Android שמבוסס על Google Play Services. הסימולטור עובר את בדיקות התקינות של המערכת ועומד בדרישות התאימות הבסיסיות של Android.

תשובות אופציונליות

אם הגדרתם את השילוב של Play Integrity API ב-Play Console או ב-Play SDK Console, תוכלו להביע הסכמה לקבלת מידע בתשובה של ה-API.

כדי לבצע שינויים בתשובות של ממשק ה-API, נכנסים ל-Play Console ועוברים אל פרסום > תקינות האפליקציה. בקטע תשובות, עורכים את השינויים ושומרים אותם.

פרטי מכשיר אופציונליים

אפליקציות ו-SDK יכולים להביע הסכמה לתוויות נוספות של מכשירים בהחלטה לגבי תקינות המכשיר. אחרי שתבחרו לקבל תוויות נוספות, תגובת תקינות הנתונים תכלול כמה תוויות לאותו מכשיר אם כל אחד מקריטריונים של התוויות יתקיים. אתם יכולים להכין את שרת הקצה העורפי כך שיגיב בצורה שונה בהתאם למגוון התשובות האפשריות. לדוגמה, אפשר לסמוך יותר על מכשיר שמחזיר שלוש תוויות (MEETS_STRONG_INTEGRITY,‏ MEETS_DEVICE_INTEGRITY ו-MEETS_BASIC_INTEGRITY) מאשר על מכשיר שמחזיר רק תווית אחת (MEETS_BASIC_INTEGRITY).

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

אפשר גם להביע הסכמה למאפייני המכשיר, שמציגים את גרסת Android SDK של מערכת Android שפועלת במכשיר. יכול להיות שבעתיד נוסיף מאפייני מכשיר נוספים.

שדה התשובה תווית תיאור
תקינות המכשיר MEETS_BASIC_INTEGRITY האפליקציה פועלת במכשיר שעובר את הבדיקות הבסיסיות של תקינות המערכת. יכול להיות שהמכשיר לא עומד בדרישות התאימות של Android ושאין לו אישור להריץ את Google Play Services. לדוגמה, יכול להיות שפועלת במכשיר גרסה לא מזוהה של Android, או שיש לו תוכנת אתחול לא נעולה, או שהוא לא אושר על ידי היצרן.
MEETS_STRONG_INTEGRITY האפליקציה פועלת במכשיר Android שמופעל על ידי Google Play Services, ויש לה הוכחה חזקה לתקינות המערכת, כמו הוכחה לתקינות האתחול שמגובת בחומרה. המכשיר עובר את בדיקות התקינות של המערכת ועומד בדרישות התאימות של Android.
בקשות רגילות לטוקן תקינות API במכשיר הזה בשעה האחרונה לכל אפליקציה בקשות לטוקן תקינות של API קלאסי במכשיר הזה בשעה האחרונה לכל אפליקציה
פעילות במכשיר מהזמן האחרון LEVEL_1 (הנמוך ביותר) 10 או פחות 5 או פחות
LEVEL_2 בין 11 ל-25 בין 6 ל-10
LEVEL_3 בין 26 ל-50 בין 11 ל-15
LEVEL_4 (הגבוה ביותר) יותר מ-50 יותר מ-15
UNEVALUATED לא בוצעה הערכה של הפעילות במכשיר מהזמן האחרון. יכול להיות שהסיבה לכך היא:
  • המכשיר לא מהימן מספיק.
  • גרסת האפליקציה שמותקנת במכשיר לא ידועה ל-Google Play.
  • היו בעיות טכניות במכשיר.
מאפייני המכשיר sdkVersion: 19, 20, ..., 35 גרסת ה-SDK של מערכת ההפעלה Android שפועלת במכשיר. המספר המוחזר ממופה אל Build.VERSION_CODES.
ריק (ערך ריק) גרסת ה-SDK לא נבדקת כי לא בוצעה בדיקה של דרישה חיונית. במקרה כזה, השדה sdkVersion לא מוגדר, ולכן השדה deviceAttributes ריק. הסיבות לכך יכולות להיות:
  • המכשיר לא מהימן מספיק.
  • גרסת האפליקציה שמותקנת במכשיר לא ידועה ל-Google Play.
  • היו בעיות טכניות במכשיר.

פרטי סביבה אופציונליים

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

אחרי שתבחרו לקבל את קביעות התקינות האלה, תגובה ה-API תכלול את השדה environment details עם תוצאת הבדיקה:

שדה התשובה ערך תיאור
קביעת סיכון הגישה לאפליקציה KNOWN_INSTALLED האפליקציות מותקנות על ידי Google Play או נטענות מראש במחיצה של המערכת על ידי יצרן המכשיר.
KNOWN_CAPTURING אפליקציות שמותקנות על ידי Google Play או מופעלות מראש במכשיר, שאפשר להשתמש בהן כדי לקרוא או לתעד את הקלט והפלט של האפליקציה המבקשת, כמו אפליקציות להקלטת מסך.
KNOWN_CONTROLLING אפליקציות שמותקנות על ידי Google Play או מוטענות מראש במכשיר פועלות, וניתן להשתמש בהן כדי לשלוט במכשיר ובכניסות ובפלט של האפליקציה המבקשת, כמו אפליקציות לשלוט מרחוק.
KNOWN_OVERLAYS אפליקציות שפועלות במכשיר, שהותקנו על ידי Google Play או הועלו מראש, ויכול להיות שהן מציגות שכבות-על באפליקציה המבקשת.
UNKNOWN_INSTALLED מותקנות אפליקציות אחרות שלא הותקנו על ידי Google Play או שהוטענו מראש במחיצה של המערכת על ידי יצרן המכשיר.
UNKNOWN_CAPTURING אפליקציות אחרות פועלות (לא הותקנו על ידי Play או נטענו מראש במכשיר) שאפשר להשתמש בהן כדי לקרוא או לתעד את הקלטות והפלט של האפליקציה המבקשת, כמו אפליקציות להקלטת מסך.
UNKNOWN_CONTROLLING אפליקציות אחרות פועלות (לא הותקנו על ידי Play או נטענו מראש במכשיר) שאפשר להשתמש בהן כדי לשלוט במכשיר ובכניסות ובפלט של האפליקציה המבקשת, כמו אפליקציות לשליטה מרחוק.
UNKNOWN_OVERLAYS אפליקציות אחרות פועלות (לא הותקנו על ידי Play או נטענו מראש במכשיר) ויכול להיות שהן מציגות שכבות-על באפליקציה המבקשת.
ריק (ערך ריק) אם לא בוצעה עמידה בדרישה מסוימת, לא תתבצע הערכה של הסיכון לגישה לאפליקציה. במקרה כזה, השדה appAccessRiskVerdict יהיה ריק. יכולות להיות לכך כמה סיבות, כולל:
  • המכשיר לא מהימן מספיק.
  • פורמט המכשיר הוא לא טלפון, טאבלט או מכשיר מתקפל.
  • במכשיר לא מותקנת מערכת Android מגרסה 6 (רמת API ‏23) ואילך.
  • גרסת האפליקציה שמותקנת במכשיר לא מוכרת ל-Google Play.
  • הגרסה של חנות Google Play במכשיר לא עדכנית.
  • משחקים בלבד: לחשבון המשתמש אין רישיון Play למשחק.
  • נעשה שימוש בבקשה רגילה עם הפרמטר verdictOptOut.
  • נעשה שימוש בבקשה רגילה עם גרסת ספרייה של Play Integrity API שעדיין לא תומכת בסיכון לגישה לאפליקציה בבקשות רגילות.
התוצאה של Play Protect NO_ISSUES שירות Play Protect מופעל ולא נמצאו בעיות באפליקציות במכשיר.
NO_DATA שירותי Play Protect מופעלים, אבל עדיין לא בוצעה סריקה. יכול להיות שהמכשיר או אפליקציית Play Store אופסו לאחרונה.
POSSIBLE_RISK שירות Play Protect מושבת.
MEDIUM_RISK שירות Play Protect מופעל ונמצאו במכשיר אפליקציות שעלולות להזיק.
HIGH_RISK Play Protect מופעל ונמצאו במכשיר אפליקציות מסוכנות.
UNEVALUATED לא בוצעה הערכה של התוצאה של Play Protect. לא בוצעה עמידה בדרישה נדרשת, למשל המכשיר לא מהימן מספיק.

הגדרת הגדרות הבקשה הקלאסיות (אופציונלי)

אפשר לדלג על הקטע הזה אם אתם מתכננים לשלוח רק בקשות API רגילות.

כששולחים בקשות רגילות, שרתי Google Play מנהלים כברירת מחדל את הצפנת התשובה שבה האפליקציה משתמשת במהלך האינטראקציה עם Play Integrity API. אנחנו ממליצים להשתמש באפשרות ברירת המחדל הזו, אבל אפשר גם לנהל ולהוריד את מפתחות ההצפנה של התשובות לפי ההוראות שבהמשך.

מתן הרשאה ל-Google לנהל את הצפנת התשובות (ברירת המחדל והאפשרות המומלצת)

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

לנהל ולהוריד בעצמי את המפתחות להצפנת תשובות

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

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

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

מעבר בין מפתחות להצפנת תשובות בניהול Google לבין מפתחות בניהול עצמי

אם Google מנהלת כרגע את ההצפנה של התשובות שלכם, ואתם רוצים לנהל ולהוריד בעצמכם את המפתחות להצפנת התשובות, עליכם לפעול לפי השלבים הבאים:

  1. נכנסים ל-Play Console.
  2. בוחרים אפליקציה שמשתמשת ב-Play Integrity API.
  3. בקטע פרסום בתפריט הימני, עוברים אל תקינות האפליקציה.
  4. לצד Play Integrity API, לוחצים על הגדרות.
  5. בקטע Classic requests בדף, לצד Response encryption, לוחצים על Edit.
  6. בחלון שמופיע, לוחצים על אני רוצה לנהל ולהוריד בעצמי את המפתחות להצפנת תשובות.
  7. פועלים לפי ההוראות כדי להעלות מפתח ציבורי.
  8. אחרי שמופיע בחלון אישור על כך שההעלאה הושלמה, לוחצים על שמירה והמפתחות המוצפנים יורדו באופן אוטומטי.
  9. משנים את הלוגיקה של השרת כך שתוכלו לפענח ולאמת אסימוני תקינות באופן מקומי, בסביבת השרת המאובטח שלכם, באמצעות מפתחות ההצפנה של התשובות.
  10. (אופציונלי) כשאתם מנהלים בעצמכם את המפתחות להצפנת התשובות, האפליקציה עדיין יכולה להשתמש בשרת של Google Play כדי לפענח ולאמת את התשובה.

אם אתם מנהלים בעצמכם את המפתחות להצפנת תשובות ואתם רוצים לעבור לניהול של Google, עליכם לפעול לפי השלבים הבאים:

  1. לשנות את הלוגיקה של השרת כך שפענוח ואימות יתבצעו רק בשרתי Google.
  2. נכנסים ל-Play Console.
  3. בוחרים אפליקציה שמשתמשת ב-Play Integrity API.
  4. בקטע פרסום בתפריט הימני, עוברים אל תקינות האפליקציה.
  5. לצד Play Integrity API, לוחצים על הגדרות.
  6. בקטע Classic requests בדף, לצד Response encryption, לוחצים על Edit.
  7. בחלון שמופיע, לוחצים על אני רוצה ש-Google תנהל את הצפנת התשובות שלי (מומלץ).
  8. לוחצים על שמירת השינויים.