Przewodnik dla programistów po interfejsie App Store Review API

App Store Review API umożliwia sklepom innych firm z aplikacjami zarejestrowanym w Google Play w ramach programu Sklep innej firmy z aplikacjami w Google Play podawanie wymaganych informacji o aplikacjach hostowanych w ich sklepie. Obejmuje to metadane aplikacji, informacje o niej, pliki binarne APK i deklaracje zgodności z zasadami.

Pełną listę punktów końcowych, metod i schematów zasobów znajdziesz w dokumentacji App Store Review API.

Zanim zaczniesz

Zanim zaczniesz wywoływać App Store Review API, musisz skonfigurować dostęp do interfejsu API, dane logowania do usługi i projekt w chmurze Google Cloud, wykonując czynności opisane w głównym przewodniku dla początkujących. App Store Review API oczekuje maksymalnie 300 żądań na minutę na sklep z aplikacjami.

Projekt i architektura interfejsu API

App Store Review API działa na podstawie wzorca migawki atomowej. Zamiast korzystać z sesji transakcyjnych, przesyłasz pliki pojedynczo, a następnie zatwierdzasz pełny stan w jednym atomowym wywołaniu:

  1. Przesyłasz poszczególne pliki i zasoby (pliki APK, obrazy i pliki zasad) w osobnych bezpośrednich wywołaniach.
  2. Zapisujesz w pamięci podręcznej zwrócone identyfikatory tych plików.
  3. Przesyłasz jedno końcowe UpdateAppStoreHostedApp żądanie, aby atomowo zatwierdzić cały stan aplikacji hostowanej.

1. Rejestracja

Aby zarejestrować aplikację hostowaną, wywołaj metodę createappstorehostedapp, podając nazwę pakietu aplikacji i nazwę pakietu sklepu. Szczegółowe informacje o schematach żądań i odpowiedzi znajdziesz w dokumentacji API.

2. Przesyłanie plików binarnych i zasobów

Po zarejestrowaniu aplikacji hostowanej musisz przesłać jej zasoby za pomocą specjalnych punktów końcowych przesyłania:

  • Pliki APK: wszystkie aktywnie rozpowszechniane pliki binarne APK aplikacji (za pomocą uploadapk).
  • Obrazy: zasoby graficzne, takie jak ikona aplikacji i zrzuty ekranu (za pomocą uploadimage).
  • Zasady: (jeśli dotyczy) dokumentacja związana z zasadami (za pomocą uploadappstoreapppolicydeclarationfile).

Zapisywanie w pamięci podręcznej i ponowne wykorzystywanie zasobów

Aby zoptymalizować przepustowość i wydajność, nie przesyłaj ponownie identycznych zasobów. Wszystkie zwrócone tokeny apkId, imageId i fileId są trwałe. Możesz zapisać te identyfikatory w pamięci podręcznej w swojej bazie danych backendu i używać ich ponownie w kolejnych aktualizacjach aplikacji hostowanej. Jeśli na przykład aktualizujesz opis aplikacji hostowanej, ale ikona aplikacji i zrzuty ekranu pozostają bez zmian, użyj tokenów imageId zapisanych w pamięci podręcznej w następnym wywołaniu aktualizacji.

3. Montaż i zatwierdzanie

Po przesłaniu wszystkich zasobów i pobraniu ich identyfikatorów musisz zmontować pełny stan aplikacji hostowanej i zatwierdzić go za pomocą metody.updateappstorehostedapp Ta metoda akceptuje pełną, atomową reprezentację szczegółów aplikacji hostowanej, zlokalizowanych informacji o niej, aktywnych zestawów plików APK i deklaracji bezpieczeństwa.

To wywołanie zastępuje każdy poprzednio aktywny stan nowym stanem opisanym w żądaniu.

Przykład treści żądania

Poniżej znajdziesz realistyczną i poprawną składniowo treść żądania JSON, która ilustruje wszystkie kluczowe elementy:

{
  "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
  ]
}

Deklaracje zgodności z zasadami

Podczas przesyłania lub aktualizowania informacji o aplikacji za pomocą interfejsu API musisz uwzględnić wszystkie wymagane deklaracje zgodności z zasadami.

Wymagania dotyczące deklaracji

Oto deklaracje, które musisz złożyć:

Wymagane w przypadku wszystkich aplikacji, aby potwierdzić, czy potrzebne są dodatkowe deklaracje:

  1. Aplikacje do dbania o zdrowie: poinformuj nas, jakich funkcji związanych ze zdrowiem używa Twoja aplikacja, abyśmy mogli określić, jakie wymagania wynikające z zasad dotyczących aplikacji do dbania o zdrowie musi ona spełniać.
  2. Funkcje finansowe: w niektórych krajach lub regionach może istnieć wymaganie, aby aplikacje zawierające funkcje finansowe były zgodne z określonymi przepisami. Prześlij dokładne i aktualne informacje o funkcjach finansowych w aplikacji, abyśmy mogli upewnić się, że przesłane treści zostaną sprawdzone przez odpowiednie zespoły.
  3. Identyfikator wyświetlania reklam: poinformuj nas, czy Twoja aplikacja korzysta z identyfikatora wyświetlania reklam.
  4. Dane logowania do testowania (dane logowania): jeśli dostęp do dowolnej części aplikacji jest ograniczony na podstawie danych logowania, subskrypcji, lokalizacji lub innych form uwierzytelniania, podaj instrukcje dostępu do aplikacji.
  5. Polityka prywatności: link do polityki prywatności aplikacji i jej szczegóły.
  6. Docelowi odbiorcy i treści: musisz podać docelową grupę wiekową swojej aplikacji i inne informacje o jej treści. Dzięki temu będziemy mieć pewność, że aplikacje przeznaczone dla dzieci są bezpieczne i odpowiednie.
  7. Reklamy: musisz nas poinformować, czy Twoja aplikacja zawiera reklamy.

Wymagane warunkowo:

  1. Aplikacje dla instytucji państwowych: poinformuj nas, czy Twoja aplikacja jest przeznaczona do użytku przez instytucje państwowe. Obejmuje to władze krajowe, stanowe, miejskie i lokalne. Pomoże nam to przekazywać Twoje zgłoszenia do odpowiednich zespołów. Jeśli ta deklaracja nie zostanie wypełniona, aplikacja nie będzie uznawana za aplikację instytucji państwowej.
  2. Standardy bezpieczeństwa dzieci: wymagane w przypadku aplikacji z kategorii „Społecznościowe” lub „Randki”. Deweloperzy aplikacji z kategorii Społeczności i Randki muszą udostępnić opublikowane standardy bezpieczeństwa i informacje kontaktowe, aby zachować zgodność z naszymi zasadami dotyczącymi standardów bezpieczeństwa dzieci.
  3. Aplikacje z wiadomościami i czasopismami: wymagane w przypadku aplikacji z kategorii „Wiadomości i czasopisma”. Dodaj szczegółowe informacje o swojej aplikacji z wiadomościami i czasopismami, aby zapewnić przejrzystość informacji o związanych z nią podmiotach.

Struktura żądania do interfejsu API

Deklaracje zgodności z zasadami są podawane w tablicy policyDeclarations w treści UpdateAppStoreHostedAppRequest. Każdy element tej tablicy jest obiektem AppStoreAppPolicyDeclaration.

Obiekt AppStoreAppPolicyDeclaration:

  • declarationId (ciąg znaków, wymagany): unikalny identyfikator deklaracji zgodności z zasadami (np. POLICY_DECLARATION_ID_FINANCE, POLICY_DECLARATION_ID_TARGET_AUDIENCE_CONTENT).
  • responses (tablica PolicyResponse, wymagana): lista odpowiedzi na pytania w ramach tej deklaracji.

Obiekt PolicyResponse:

  • questionId (ciąg znaków, wymagany): unikalny identyfikator konkretnego pytania, na które udzielana jest odpowiedź (np. POLICY_QUESTION_ID_FINANCIAL_PRODUCT_TYPES, POLICY_QUESTION_ID_TAC_TARGET_AGE_GROUPS).
  • value (wymagany): sama odpowiedź, która może być jednym z tych typów:
    • booleanResponse: w przypadku pytań, na które można odpowiedzieć „Tak” lub „Nie”.
      • value (wartość logiczna)
    • stringResponse: w przypadku odpowiedzi w postaci zwykłego tekstu, w tym adresów URL.
      • value (ciąg znaków)
    • singleChoiceResponse: gdy z listy można wybrać tylko 1 opcję.
      • value (ciąg znaków): identyfikator wybranej odpowiedzi.
    • multipleChoiceResponse: gdy można wybrać kilka opcji.
      • values (tablica ciągów znaków): identyfikatory wybranych odpowiedzi.
    • documentResponse: w przypadku pytań wymagających przesłania dokumentu. Więcej informacji znajdziesz w sekcji Obsługa przesyłania dokumentów.
    • groupResponse: w przypadku powtarzających się zestawów pytań zagnieżdżonych.
    • keyedGroupResponse: w przypadku zestawów pytań zagnieżdżonych pogrupowanych według określonego klucza.

Przykładowe fragmenty kodu dotyczące deklaracji znajdziesz w szczegółowym przewodniku.

Obsługa przesyłania dokumentów

W przypadku niektórych pytań dotyczących zasad musisz podać dokumenty potwierdzające (np. licencje na funkcje finansowe). Dokumentów nie można osadzać bezpośrednio w UpdateAppStoreHostedAppRequest. Zamiast tego musisz:

  1. Przesłać dokument: użyj UploadAppStoreAppPolicyDeclarationFile punktu końcowego. Jest to żądanie przesłania multimediów. Wartość fileType powinna być ustawiona na DECLARATION_FILE_TYPE_DOCUMENT.

    • Punkt końcowy: POST /androidpublisher/v3/appstore/{appStorePackageName}/apps/{packageName}/policyDeclarationFiles:upload
    • Odpowiedzi na udane przesłanie będą zawierać fileId.

  2. Odwołać się do identyfikatora dokumentu: w PolicyResponse dla pytania dotyczącego dokumentu użyj typu documentResponse. Wypełnij pole documentId wartością fileId uzyskaną w kroku przesyłania.

Obiekt PolicyDocumentResponse:

  • documentId (ciąg znaków, wymagany): identyfikator zwrócony przez UploadAppStoreAppPolicyDeclarationFile punkt końcowy.
  • expiryDate (data, opcjonalny): data ważności dokumentu, jeśli dotyczy.
  • nonExpiring (wartość logiczna, opcjonalny): ustaw na true, jeśli dokument nie wygasa.

Przykład odpowiedzi dotyczącej dokumentu:

// 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. Sprawdzanie dostępności

Gdy zatwierdzisz stan aplikacji hostowanej za pomocą UpdateAppStoreHostedApp, aplikacja zostanie automatycznie przetworzona i oznaczona jako opublikowana domyślnie w Google Play dla sklepu innej firmy z aplikacjami.

Aby kontrolować dostępność aplikacji po jej zatwierdzeniu, wywołaj metodę updateappstorehostedapppublishstatus , aby zaktualizować jej stan:

  • Wycofywanie publikacji aplikacji: aby aplikacja hostowana była niedostępna, ustaw pole publishState na APP_STORE_APP_PUBLISH_STATE_UNPUBLISHED.
  • Ponowne publikowanie aplikacji: aby ponownie udostępnić wcześniej nieopublikowaną aplikację bez modyfikowania informacji o niej ani ponownego przesyłania zasobów, ustaw pole publishState na APP_STORE_APP_PUBLISH_STATE_PUBLISHED.