הוספה של Play Integrity API

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

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

  • מכשירים וסביבות בסיכון: הקביעה deviceIntegrity עוזרת לכם לקבוע אם האפליקציה שלכם פועלת במחשב מקורי או במופע מקורי של Google Play Games למחשב.

שילוב עם ה-API

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

  1. הכנת טוקן היושרה
  2. בקשה לקבלת טוקן מהימנות
  3. בקשת נתוני טוקן

הגדרה ראשונית ב-Google Cloud Console

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

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

שלב 1: הכנת אסימון יושרה

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

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

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

פרטים
פרמטרים ‫params: פרמטרים שמכילים מספר פרויקט ב-Google Cloud. ‫
continuation: הקריאה החוזרת האסינכרונית להחזרת ספק אסימון השלמות.

שלב 2: מבקשים את אסימון היושרה

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

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

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

כשבודקים פעולת משתמש באפליקציה באמצעות Play Integrity API למחשב, אפשר להשתמש בשדה RequestIntegrityTokenParams::request_hash כדי לצמצם את הסיכון להתקפות של שיבוש. לדוגמה, משחק מסוים רוצה לדווח על הניקוד של השחקן לשרת העורפי של המשחק, והשרת שלכם רוצה לוודא ששרת proxy לא שינה את הניקוד הזה. ‫Play Integrity API מחזיר את הערך שהגדרתם בשדה הזה, בתוך תגובת היושרה החתומה. בלי requestHash, אסימון היושרה יהיה קשור רק למכשיר, ולא לבקשה הספציפית, מה שפותח פתח למתקפה.

כדי למנוע את הבעיה הזו כשמבקשים קביעת תקינות:

  • מחשבים תקציר של כל פרמטרי הבקשה הרלוונטיים (למשל, SHA256 של סדרת בקשות יציבה) מפעולת המשתמש או מבקשת השרת שמתרחשת.
  • מגדירים את השדה RequestIntegrityTokenParams::request_hash לערך הגיבוב.
פרטים
פרמטרים ‫params: פרמטרים שמכילים את RequestTokenData המוכן ואת הגיבוב של בקשת בדיקת השלמות. ‫
continuation: הקריאה החוזרת האסינכרונית להחזרת הנתונים.

שלב 3: מבקשים נתוני טוקן

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

  1. יוצרים חשבון שירות בפרויקט Google Cloud שמקושר לאפליקציה.

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

    playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
 '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'

  3. קוראים את תגובת ה-JSON.

המטען הייעודי (payload) שמתקבל הוא טוקן טקסט פשוט שמכיל את תוצאות הבדיקה של תקינות המכשיר ופרטים, לצד מידע שהמפתחים סיפקו. הפורמט של האסימון הוא:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

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

שדה פרטי הבקשה

השדה requestDetails מכיל מידע על הבקשה, כולל מידע שהמפתח סיפק בשדה requestHash לבקשות רגילות ובשדה nonce לבקשות קלאסיות.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

הערכים האלה צריכים להיות זהים לאלה של הבקשה המקורית. לכן, צריך לוודא שחלק requestDetails במטען הייעודי (payload) של ה-JSON תואם לערכים של requestPackageName ו-requestHash שנשלחו בבקשה המקורית.

שדה תקינות המכשיר

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

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

כברירת מחדל, deviceRecognitionVerdict יכול להכיל את הרכיבים הבאים:

MEETS_PC_INTEGRITY
מחזירה פסק דין אם האפליקציה פועלת בסביבת מחשב מקורית, שבה לא זוהה שיבוש במכשיר.
ריק (ערך ריק)
האפליקציה פועלת במכשיר שיש בו סימנים למתקפה (למשל, API hooking) או לפריצה למערכת (למשל, rooting), או שהאפליקציה לא פועלת במכשיר פיזי (למשל, אמולטור שלא עובר את בדיקות התקינות של Google Play).

מגבלות שימוש

מגבלות השימוש ב-Play Integrity API

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

פעולה מכסה יומית לכל אפליקציה הערות
בקשות לטוקנים 10,000 הנתונים משותפים בין Play Integrity API למחשב ובין Play Integrity API לבקשות רגילות וקלאסיות
פענוח טוקנים בשרתים של Google 10,000 הנתונים משותפים בין Play Integrity API למחשב ובין Play Integrity API לבקשות קלאסיות ורגילות

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

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

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

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

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

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

שיקולי אבטחה

כדי להפיק את הערך המרבי מ-Play Integrity API, מומלץ לפעול לפי השיטות המומלצות הבאות:

יש לכם אסטרטגיה למניעת ניצול לרעה

‫Play Integrity API פועל הכי טוב בשילוב עם אותות אחרים, כחלק מהאסטרטגיה הכוללת למניעת ניצול לרעה ולא בתור המנגנון היחיד למניעת ניצול לרעה. מומלץ להשתמש ב-API הזה בשילוב עם שיטות מומלצות אחרות לאבטחת האפליקציה. כברירת מחדל, האפליקציה יכולה לשלוח עד 10,000 בקשות ביום בכל ההתקנות. אפשר לבקש להגדיל את המקסימום היומי.

איסוף טלמטריה והבנת הקהל לפני נקיטת פעולה

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

שליחת בקשה לקביעת תקינות ברגע המתאים

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

איך מקשים על שכפול בקשות API

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

הימנעות משמירת קביעות תקינות במטמון

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

שליחת טווח של תגובות מהשרת לאפליקציה

קשה יותר לשכפל מגוון של תוצאות החלטה מאשר לשלוח תגובה בינארית של אישור או דחייה מהשרת בחזרה לאפליקציה לכל תגובה. לדוגמה, אפשר להשתמש בסדרה של תגובות קשורות כמו Allow (אישור), Allow with limits (אישור עם הגבלות), Allow with limits after CAPTCHA completion (אישור עם הגבלות אחרי השלמת CAPTCHA) ו-Deny (דחייה).

הצגת הודעות שגיאה עם אפשרות לביצוע פעולה

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

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

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

תנאים והגבלות ובטיחות נתונים

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

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