App Store Review API Developer Guide

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

רשימה מלאה של נקודות קצה, שיטות וסכימות של משאבים זמינה בחומר העזר בנושא App Store Review API.

לפני שתתחיל

כדי לבצע קריאות ל-App Store Review API, צריך להשלים את ההגדרה של גישת ה-API, פרטי הכניסה לשירות ופרויקט Google Cloud באמצעות המדריך הראשי לתחילת העבודה. ‫App Store Review API מצפה ל-300 בקשות לכל היותר לדקה לכל חנות אפליקציות.

API Design & Architecture

ה-App Store Review API פועל לפי דפוס של תמונת מצב אטומית. במקום להשתמש בסשנים טרנזקציונליים, מעלים קבצים בנפרד ואז מבצעים קומיט של המצב המלא בקריאה אטומית אחת:

  1. אתם מעלים קבצים ונכסים בודדים (קובצי APK, תמונות וקובצי מדיניות) בקריאות נפרדות וישירות.
  2. שומרים במטמון את מזהי הקבצים שהוחזרו.
  3. שולחים בקשה סופית אחת של UpdateAppStoreHostedApp לביצוע (commit) של כל מצב האפליקציה המתארחת באופן אטומי.

1. הרשמה

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

2. העלאות של קבצים בינאריים ונכסים

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

  • ‫APKs: כל הקבצים הבינאריים של ה-APK של האפליקציה שמופצים באופן פעיל (באמצעות uploadapk).
  • תמונות: נכסי תמונות, כמו סמל האפליקציה וצילומי מסך (באמצעות uploadimage).
  • מדיניות: (אם רלוונטי) מסמכי מדיניות (באמצעות uploadappstoreapppolicydeclarationfile).

שימוש חוזר בנכסים ושמירתם במטמון

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

3. הרכבה ושמירה

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

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

דוגמה לגוף הבקשה

הנה גוף בקשת JSON ריאלי ותקין מבחינת תחביר, שממחיש את כל רכיבי המפתח:

{
  "appStorePackageName": "com.example.thirdparty.store",
  "packageName": "com.example.hostedapp.game",
  "appDetails": {
    "developerName": "Adventure Games Studio Ltd.",
    "contactEmail": "support@adventuregames.example.com",
    "developerWebsite": "https://adventuregames.example.com"
  },
  "activeLocalizedStoreListings": [
    {
      "languageCode": "en-US",
      "appName": "Super Quest Legends",
      "shortDescription": "An epic fantasy RPG adventure.",
      "fullDescription": "Super Quest Legends is an immersive action RPG featuring real-time battles, customizable classes, and a deep fantasy narrative. Journey through a magical realm, fight epic bosses, and team up with friends in dungeon raids.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ],
      "videoLink": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    },
    {
      "languageCode": "es-ES",
      "appName": "Super Quest Leyendas",
      "shortDescription": "Una aventura épica de RPG fantástico.",
      "fullDescription": "Super Quest Leyendas es un RPG de acción inmersivo con batallas en tiempo real, clases personalizables y una profunda narrativa de fantasía. Viaja a través de un reino mágico, lucha contra jefes épicos y únete a amigos en incursiones.",
      "appIconId": "987123",
      "screenshotId": [
        "102938",
        "475869",
        "384756"
      ]
    }
  ],
  "activeApks": {
    "activeApkSets": [
      {
        "baseApkId": "554433"
      },
      {
        "baseApkId": "990011"
      }
    ]
  },
  "policyDeclarations": [
    {
      "declarationId": "POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS",
          "multipleChoiceResponse": {
            "values": [
              "POLICY_RESPONSE_CHOICE_ID_TAC_AGE_EIGHTEEN_AND_ABOVE"
            ]
          }
        },
        // ... other responses for TAC
      ]
    },
    {
      "declarationId": "POLICY_DECLARATION_ID_ADVERTISING_ID",
      "responses": [
        {
          "questionId": "POLICY_QUESTION_ID_AD_ID_IS_USED",
          "booleanResponse": {
            "value": false
          }
        }
        // ... other responses for AD_ID
      ]
    }
    // ... other declarations
  ]
}

הצהרות לגבי תאימות למדיניות

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

דרישות לגבי הצהרה

ההצהרות הבאות כלולות בהיקף:

חובה לכל האפליקציות כדי לאשר אם נדרשות הצהרות נוספות:

  1. אפליקציות בתחום הבריאות: כדי לעזור לנו להבין באילו דרישות האפליקציה חייבת לעמוד במסגרת המדיניות בנושא אפליקציות בתחום הבריאות, יש להוסיף באילו תכונות שקשורות לבריאות נעשה שימוש באפליקציה.
  2. תכונות פיננסיות: יכול להיות שאפליקציות שמספקות תכונות פיננסיות יצטרכו לעמוד בתקנות מסוימות במדינות או באזורים מסוימים. חשוב לשלוח פרטים מדויקים ועדכניים על התכונות הפיננסיות באפליקציה כדי לעזור לנו לוודא שהצוותים הנכונים יבדקו את הבקשה ששלחת.
  3. מזהה פרסום: אנחנו צריכים לדעת אם האפליקציה משתמשת במזהה פרסום.
  4. פרטי כניסה לבדיקה: אם יש חלקים באפליקציה שהגישה אליהם מוגבלת על סמך פרטי כניסה, מינויים, מיקום או אמצעי אימות אחרים, עליך לספק הוראות לגישה אליהם.
  5. מדיניות פרטיות: קישור למדיניות הפרטיות של האפליקציה ופרטים עליה.
  6. קהל היעד והתוכן: חובה להודיע לנו מהי קבוצת הגיל של קהל היעד לאפליקציה ולתת לנו מידע נוסף על התוכן שלה. כך אנחנו יכולים לוודא שאפליקציות שמיועדות לילדים בטוחות ומתאימות.
  7. מודעות: חובה ליידע אותנו אם האפליקציה מכילה מודעות.

חובה בתנאים מסוימים:

  1. אפליקציות ממשלתיות: צריך להודיע לנו אם האפליקציה מיועדת לשימוש של גורם ממשלתי כלשהו. כולל מוסדות ממשלתיים ברמה הלאומית, ברמת המדינה וברמת העיר, ורשויות מקומיות. כך נוכל לוודא שהצוותים המתאימים יבדקו את האפליקציה ששלחת. אם לא תמלאו את ההצהרה הזו, האפליקציה תיחשב כאפליקציה שלא מיועדת למגזר הממשלתי.
  2. תקנים לבטיחות ילדים: חובה באפליקציות בקטגוריות 'רשתות חברתיות' או 'שירותי היכרויות'. באפליקציות ששייכות לקטגוריות של רשתות חברתיות או שירותי היכרויות, חייבים לספק תקני בטיחות שפורסמו ופרטים ליצירת קשר כדי לעמוד בדרישות המדיניות בנושא תקנים לבטיחות ילדים.
  3. אפליקציות של חדשות וכתבי עת: חובה באפליקציות בקטגוריה 'חדשות וכתבי עת'. כדי לספק שקיפות לגבי הישויות שמאחורי אפליקציית החדשות וכתב העת שלך, עליך להוסיף עליה פרטים.

מבנה בקשת API

הצהרות התאימות למדיניות מופיעות במערך policyDeclarations בגוף של UpdateAppStoreHostedAppRequest. כל פריט במערך הזה הוא אובייקט AppStoreAppPolicyDeclaration.

AppStoreAppPolicyDeclaration אובייקט:

  • ‫declarationId (מחרוזת, חובה): המזהה הייחודי של הצהרת המדיניות (לדוגמה, POLICY_DECLARATION_ID_FINANCE,‏ POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • ‫responses (מערך של PolicyResponse, חובה): רשימה של תשובות לשאלות בהצהרה הספציפית הזו.

PolicyResponse אובייקט:

  • ‫questionId (מחרוזת, חובה): המזהה הייחודי של השאלה הספציפית שעליה ניתנת תשובה (לדוגמה, POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES,‏ POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • ‫value (חובה): התשובה עצמה, שיכולה להיות אחת מהסוגים הבאים:
    • ‫booleanResponse: לשאלות עם תשובות של 'כן' או 'לא'.
      • value (בוליאני)
    • ‫stringResponse: תשובות בטקסט פשוט, כולל כתובות URL.
      • value (מחרוזת)
    • ‫singleChoiceResponse: כשניתן לבחור רק אפשרות אחת מתוך רשימה.
      • ‫value (מחרוזת): המזהה של התשובה שנבחרה.
    • ‫multipleChoiceResponse: כשניתן לבחור כמה אפשרויות.
      • ‫values (מערך של מחרוזות): המזהים של אפשרויות התשובה שנבחרו.
    • ‫documentResponse: לשאלות שדורשות העלאת מסמך. איך מעלים מסמכים
    • ‫groupResponse: עבור קבוצות חוזרות של שאלות מוטמעות.
    • ‫keyedGroupResponse: עבור קבוצות של שאלות מוטמעות שמקובצות לפי מפתח ספציפי.

דוגמאות לקטעי קוד להצהרה מופיעות במדריך המפורט.

טיפול בהעלאות של מסמכים

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

  1. העלאת המסמך: משתמשים בנקודת הקצה UploadAppStoreAppPolicyDeclarationFile. זו בקשה להעלאת מדיה. הערך של fileType צריך להיות DECLARATION_FILE_TYPE_DOCUMENT.

    • נקודת קצה (endpoint): POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • תשובות להעלאה מוצלחת יכללו את הערך fileId.

  2. הפניה למזהה המסמך: בשאלה PolicyResponse לגבי המסמך, משתמשים בסוג documentResponse. מזינים את הערך fileId שקיבלתם בשלב ההעלאה בשדה documentId.

PolicyDocumentResponse אובייקט:

  • ‫documentId (מחרוזת, חובה): המזהה שמוחזר מנקודת הקצה UploadAppStoreAppPolicyDeclarationFile.
  • ‫expiryDate (תאריך, אופציונלי): תאריך התפוגה של המסמך, אם רלוונטי.
  • ‫nonExpiring (boolean, אופציונלי): מגדירים את הערך true אם המסמך לא פג תוקף.

דוגמה לתשובה של מסמך:

// Inside a PolicyResponse object
{
  "questionId": "POLICY_QUESTION_ID_FINANCE_CRYPTO_US_FINCEN_LICENSE", // Example ID
  "documentResponse": {
    "documentId": "123456789", // The fileId from upload
    "expiryDate": {
      "year": 2027,
      "month": 6,
      "day": 1
    }
  }
}

4. שליטה בזמינות

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

כדי לשלוט בזמינות של האפליקציה אחרי שהיא אושרה, צריך להפעיל את השיטה updateappstorehostedapppublishstatus כדי לעדכן את הסטטוס שלה:

  • ביטול הפרסום של אפליקציה: כדי להפוך את האפליקציה המארחת ללא זמינה, צריך להגדיר את השדה publishState לערך APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • פרסום מחדש של אפליקציה: כדי להפוך אפליקציה שלא פורסמה בעבר לזמינה שוב בלי לשנות את כרטיסי המוצר או להעלות מחדש נכסים, צריך להגדיר את השדה publishState לערך APP_STORE_APP_PUBLISH_STATE_PUBLISHED.