Questa pagina descrive come gestire i problemi relativi agli esiti di integrità.
Dopo aver richiesto un token di integrità, hai la possibilità di mostrare all'utente una finestra di dialogo di Google Play. Puoi mostrare la finestra di dialogo quando si verifica uno o più problemi con l'esito relativo all'integrità o se si è verificata un'eccezione durante una richiesta dell'API Integrity. Una volta chiusa la finestra di dialogo, puoi verificare che il problema sia stato risolto con un'altra richiesta di token di integrità. Se effettui richieste standard, devi eseguire di nuovo il warmup del fornitore di token per ottenere un nuovo esito.
Richiedere una finestra di dialogo di integrità per risolvere un problema relativo all'esito
Quando il client richiede un token di integrità, puoi utilizzare il metodo offerto in
the StandardIntegrityToken (API Standard) e
IntegrityTokenResponse (API Classic):
showDialog(Activity activity, int integrityDialogTypeCode).
I seguenti passaggi descrivono come utilizzare l'API Play Integrity per mostrare una
finestra di dialogo di correzione utilizzando il GET_LICENSED codice della finestra di dialogo.
Gli altri codici delle finestre di dialogo che la tua app può richiedere sono elencati dopo questa sezione.
Richiedi un token di integrità dalla tua app e invialo al tuo server. Puoi utilizzare la richiesta standard o classica.
Kotlin
// Request an integrity token val tokenResponse: StandardIntegrityToken = requestIntegrityToken() // Send token to app server and get response on what to do next val yourServerResponse: YourServerResponse = sendToServer(tokenResponse.token())
Java
// Request an integrity token StandardIntegrityToken tokenResponse = requestIntegrityToken(); // Send token to app server and get response on what to do next YourServerResponse yourServerResponse = sendToServer(tokenResponse.token());
Unità
// Request an integrity token StandardIntegrityToken tokenResponse = RequestIntegrityToken(); // Send token to app server and get response on what to do next YourServerResponse yourServerResponse = sendToServer(tokenResponse.Token);
Unreal Engine
// Request an integrity token StandardIntegrityToken* Response = RequestIntegrityToken(); // Send token to app server and get response on what to do next YourServerResponse YourServerResponse = SendToServer(Response->Token);
Nativo
/// Request an integrity token StandardIntegrityToken* response = requestIntegrityToken(); /// Send token to app server and get response on what to do next YourServerResponse yourServerResponse = sendToServer(StandardIntegrityToken_getToken(response));
Sul tuo server, decripta il token di integrità e controlla il campo
appLicensingVerdict. Potrebbe avere un aspetto simile al seguente:// Licensing issue { ... "accountDetails": { "appLicensingVerdict": "UNLICENSED" } }
Se il token contiene
appLicensingVerdict: "UNLICENSED", rispondi al client della tua app chiedendogli di mostrare la finestra di dialogo relativa alla licenza:Kotlin
private fun getDialogTypeCode(integrityToken: String): Int{ // Get licensing verdict from decrypted and verified integritytoken val licensingVerdict: String = getLicensingVerdictFromDecryptedToken(integrityToken) return if (licensingVerdict == "UNLICENSED") { 1 // GET_LICENSED } else 0 }
Java
private int getDialogTypeCode(String integrityToken) { // Get licensing verdict from decrypted and verified integrityToken String licensingVerdict = getLicensingVerdictFromDecryptedToken(integrityToken); if (licensingVerdict.equals("UNLICENSED")) { return 1; // GET_LICENSED } return 0; }
Unità
private int GetDialogTypeCode(string IntegrityToken) { // Get licensing verdict from decrypted and verified integrityToken string licensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken); if (licensingVerdict == "UNLICENSED") { return 1; // GET_LICENSED } return 0; }
Unreal Engine
private int GetDialogTypeCode(FString IntegrityToken) { // Get licensing verdict from decrypted and verified integrityToken FString LicensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken); if (LicensingVerdict == "UNLICENSED") { return 1; // GET_LICENSED } return 0; }
Nativo
private int getDialogTypeCode(string integrity_token) { /// Get licensing verdict from decrypted and verified integrityToken string licensing_verdict = getLicensingVerdictFromDecryptedToken(integrity_token); if (licensing_verdict == "UNLICENSED") { return 1; // GET_LICENSED } return 0; }
Nella tua app, chiama
showDialogcon il codice richiesto recuperato dal tuo server:Kotlin
// Show dialog as indicated by the server val showDialogType: Int? = yourServerResponse.integrityDialogTypeCode() if (showDialogType == null) { return } // Create dialog request val dialogRequest = StandardIntegrityDialogRequest.builder() .setActivity(activity) .setTypeCode(showDialogType) .setStandardIntegrityResponse(StandardIntegrityResponse.TokenResponse(token)) .build() // Call showDialog, the dialog will be shown on top of the provided activity // and the task will complete when the dialog is closed. val result: Task<Int> = standardIntegrityManager.showDialog(dialogRequest) // Handle response code, call the Integrity API again to confirm that the // verdict issue has been resolved.
Java
// Show dialog as indicated by the server @Nullable Integer showDialogType = yourServerResponse.integrityDialogTypeCode(); if (showDialogType == null) { return; } // Create dialog request StandardIntegrityDialogRequest dialogRequest = StandardIntegrityDialogRequest.builder() .setActivity(getActivity()) .setTypeCode(showDialogTypeCode) .setStandardIntegrityResponse(new StandardIntegrityResponse.TokenResponse(token)) .build(); // Call showDialog, the dialog will be shown on top of the provided activity // and the task will complete when the dialog is closed. Task<Integer> result = standardIntegrityManager.showDialog(dialogRequest); // Handle response code, call the Integrity API again to confirm that the // verdict issue has been resolved.
Unità
// Initialize the V2 manager. Requires Play Integrity Unity Plugin v2.0.0 or // higher. var standardIntegrityManager = new StandardIntegrityManagerV2(); IEnumerator ShowDialogCoroutine() { int showDialogType = yourServerResponse.IntegrityDialogTypeCode(); PlayAsyncOperation<IntegrityDialogResponseCode, StandardIntegrityError> showDialogTask; using (var activity = UnityPlayerHelper.GetCurrentActivity()) { // Create a dialog request var dialogRequest = new StandardIntegrityDialogRequest(tokenResponse, activity, showDialogType); // Call showDialog with the request, the dialog will be shown on top of the // provided activity and complete when the dialog is closed. showDialogTask = standardIntegrityManager.ShowDialog(dialogRequest); } // Wait for PlayAsyncOperation to complete. yield return showDialogTask; // Handle response code, call the Integrity API again to confirm that the // verdict issue been resolved. }
Unreal Engine
// .h void MyClass::OnShowDialogCompleted( EStandardIntegrityErrorCode Error, EIntegrityDialogResponseCode Response) { // Handle response code, call the Integrity API again to confirm that the // verdict issue has been resolved. } // .cpp void MyClass::RequestIntegrityToken() { UStandardIntegrityToken* Response = ... int TypeCode = YourServerResponse.integrityDialogTypeCode(); // Create a delegate to bind the callback function. FShowDialogStandardOperationCompletedDelegate Delegate; // Bind the completion handler (OnShowDialogCompleted) to the delegate. Delegate.BindDynamic(this, &MyClass::OnShowDialogCompleted); // Call ShowDialog with TypeCode which completes when the dialog is closed. Response->ShowDialog(TypeCode, Delegate); }
Nativo
// Show dialog as indicated by the server int show_dialog_type = yourServerResponse.integrityDialogTypeCode(); if(show_dialog_type == 0){ return; } /// Create dialog request StandardIntegrityDialogRequest* dialog_request; StandardIntegrityDialogRequest_create(&dialog_request); StandardIntegrityDialogRequest_setTypeCode(dialog_request, show_dialog_type); StandardIntegrityDialogRequest_setActivity(dialog_request, activity); StandardIntegrityDialogRequest_setStandardIntegrityToken(dialog_request, token_response); /// Call showDialog with the dialog request. The dialog will be shown on top /// of the provided activity and complete when the dialog is closed by the /// user. StandardIntegrityDialogResponse* dialog_response; StandardIntegrityErrorCode error_code = StandardIntegrityManager_showDialog(dialog_request, &dialog_response); /// Use polling to wait for the async operation to complete. Note, the polling /// shouldn't block the thread where the StandardIntegrityManager is running. IntegrityDialogResponseCode response_code = INTEGRITY_DIALOG_RESPONSE_UNKNOWN; while (error_code == STANDARD_INTEGRITY_NO_ERROR) { error_code = StandardIntegrityDialogResponse_getResponseCode(dialog_response, &response_code); if(response_code != INTEGRITY_DIALOG_RESPONSE_UNKNOWN){ break; } } /// Free memory StandardIntegrityDialogRequest_destroy(dialog_request); StandardIntegrityDialogResponse_destroy(dialog_response); /// Handle response code, call the Integrity API again to confirm that the /// verdict issues have been resolved.
La finestra di dialogo viene visualizzata sopra l'attività fornita. Quando l'utente ha chiuso la finestra di dialogo, l'attività viene completata con un codice di risposta.
(Facoltativo) Richiedi un altro token per visualizzare altre finestre di dialogo. Se effettui richieste standard, devi eseguire di nuovo il warmup del fornitore di token per ottenere un nuovo esito.
Richiedere una finestra di dialogo di integrità per correggere un'eccezione lato client
Se una richiesta dell'API Integrity non va a buon fine con una StandardIntegrityException
(API Standard) o IntegrityServiceException (API Classic) e l'
eccezione è correggibile, puoi utilizzare le finestre di dialogo GET_INTEGRITY o
GET_STRONG_INTEGRITY per correggere l'errore.
I seguenti passaggi descrivono come utilizzare la GET_INTEGRITY
finestra di dialogo per correggere un errore lato client correggibile segnalato dall'API Integrity.
Verifica che l'eccezione restituita da una richiesta dell'API Integrity sia correggibile.
Kotlin
private fun isExceptionRemediable(exception: ExecutionException): Boolean { val cause = exception.cause if (cause is StandardIntegrityException && cause.isRemediable) { return true } return false }
Java
private boolean isExceptionRemediable(ExecutionException exception) { Throwable cause = exception.getCause(); if (cause instanceof StandardIntegrityException integrityException && integrityException.isRemediable()) { return true; } return false; }
Unità
private bool IsExceptionRemediable(StandardIntegrityError error) { // Check if the operation resulted in a remediable error if (error != null && error.ErrorCode != StandardIntegrityErrorCode.NoError && error.IsRemediable) { return true; } return false; }
Nativo
bool IsErrorRemediable(StandardIntegrityToken* token) { /// Check if the error associated with the token is remediable bool isRemediable = false; if(StandardIntegrityToken_getIsRemediable(response, &isRemediable) == STANDARD_INTEGRITY_NO_ERROR){ return isRemediable; } return false; }
Se l'eccezione è correggibile, richiedi la finestra di dialogo
GET_INTEGRITYutilizzando l'eccezione restituita. La finestra di dialogo verrà visualizzata sopra l'attività fornita e l'attività restituita verrà completata con un codice di risposta dopo che l'utente avrà chiuso la finestra di dialogo.Kotlin
private fun showDialog(exception: StandardIntegrityException) { // Create a dialog request val standardIntegrityDialogRequest = StandardIntegrityDialogRequest.builder() .setActivity(activity) .setType(IntegrityDialogTypeCode.GET_INTEGRITY) .setStandardIntegrityResponse(ExceptionDetails(exception)) .build() // Request dialog val responseCode: Task<Int> = standardIntegrityManager.showDialog(standardIntegrityDialogRequest) }
Java
private void showDialog(StandardIntegrityException exception) { // Create a dialog request StandardIntegrityDialogRequest standardIntegrityDialogRequest = StandardIntegrityDialogRequest.builder() .setActivity(this.activity) .setType(IntegrityDialogTypeCode.GET_INTEGRITY) .setStandardIntegrityResponse(new ExceptionDetails(exception)) .build(); // Request dialog Task<Integer> responseCode = standardIntegrityManager.showDialog(standardIntegrityDialogRequest); }
Unità
// Initialize the V2 manager. Requires Play Integrity Unity Plugin v2.0.0 or // higher. var standardIntegrityManager = new StandardIntegrityManagerV2(); IEnumerator ShowDialogToFixError(StandardIntegrityError error) { PlayAsyncOperation<IntegrityDialogResponseCode, StandardIntegrityError> showDialogTask; using (var activity = UnityPlayerHelper.GetCurrentActivity()) { // Create a dialog request using the error var dialogRequest = new StandardIntegrityDialogRequest(error, activity, GET_INTEGRITY_DIALOG); // Request dialog showDialogTask = standardIntegrityManager.ShowDialog(dialogRequest); } // Wait for PlayAsyncOperation to complete. yield return showDialogTask; }
Nativo
private void showDialogToFixError(StandardIntegrityToken* token) { /// If the token request failed, and the underlying error is not fixable /// then return early if(isErrorRemediable(token)) { return; } /// Create dialog request StandardIntegrityDialogRequest* dialog_request; StandardIntegrityDialogRequest_create(&dialog_request); StandardIntegrityDialogRequest_setTypeCode(dialog_request, kGetIntegrityDialogTypeCode); StandardIntegrityDialogRequest_setActivity(dialog_request, activity); StandardIntegrityDialogRequest_setStandardIntegrityToken(dialog_request, token_response); /// Call showDialog with the dialog request. The dialog will be shown on /// top of the provided activity and complete when the dialog is closed by /// the user. StandardIntegrityDialogResponse* dialog_response; StandardIntegrityErrorCode error_code = StandardIntegrityManager_showDialog(dialog_request, &dialog_response); /// Use polling to wait for the async operation to complete. /// Note, the polling shouldn't block the thread where the /// StandardIntegrityManager is running. IntegrityDialogResponseCode response_code = INTEGRITY_DIALOG_RESPONSE_UNKNOWN; while (error_code == STANDARD_INTEGRITY_NO_ERROR) { error_code = StandardIntegrityDialogResponse_getResponseCode(response, &response_code); if(response_code != INTEGRITY_DIALOG_RESPONSE_UNKNOWN){ break; } } /// Free memory StandardIntegrityDialogRequest_destroy(dialog_request); StandardIntegrityDialogResponse_destroy(dialog_response); }
Se il codice di risposta restituito indica un esito positivo, la successiva richiesta di un token di integrità dovrebbe andare a buon fine senza eccezioni. Se effettui richieste standard, devi eseguire di nuovo il warmup del fornitore di token per ottenere un nuovo esito.
Codici delle finestre di dialogo di integrità
GET_LICENSED (codice tipo 1)
Problema relativo all'esito
Questa finestra di dialogo è appropriata per due problemi:
- Accesso non autorizzato:
appLicensingVerdict: "UNLICENSED". Ciò significa che l'account utente non ha diritto alla tua app, il che può accadere se l'utente l'ha eseguita tramite sideload o l'ha acquisita da un app store diverso da Google Play. - App manomessa:
appRecognitionVerdict: "UNRECOGNIZED_VERSION". Ciò significa che il file binario della tua app è stato modificato o non è una versione riconosciuta da Google Play.
Correzione
Puoi mostrare la finestra di dialogo GET_LICENSED per chiedere all'utente di acquisire l'app originale da Google Play. Questa singola finestra di dialogo risolve entrambi gli scenari:
- Per un utente senza licenza, gli concede una licenza Play. In questo modo l'utente può ricevere gli aggiornamenti delle app da Google Play.
- Per un utente con una versione manomessa dell'app, lo guida all'installazione dell'app non modificata da Google Play.
Quando l'utente completa la finestra di dialogo, i controlli di integrità successivi restituiscono
appLicensingVerdict: "LICENSED" e appRecognitionVerdict: "PLAY_RECOGNIZED".
Esempio di UX
CLOSE_UNKNOWN_ACCESS_RISK (codice tipo 2)
Problema relativo all'esito
Quando environmentDetails.appAccessRiskVerdict.appsDetected contiene
"UNKNOWN_CAPTURING" o "UNKNOWN_CONTROLLING", significa che sul dispositivo sono in esecuzione altre app
(non installate da Google Play o precaricate nella partizione di sistema dal produttore del dispositivo) che potrebbero acquisire lo schermo o
controllare il dispositivo.
Correzione
Puoi mostrare la finestra di dialogo CLOSE_UNKNOWN_ACCESS_RISK per chiedere all'utente di chiudere tutte le app sconosciute che potrebbero acquisire lo schermo o controllare il dispositivo.
Se l'utente tocca il pulsante Close all, tutte queste app vengono chiuse.
Esempio di UX
CLOSE_ALL_ACCESS_RISK (codice tipo 3)
Problema relativo all'esito
Quando environmentDetails.appAccessRiskVerdict.appsDetected contiene uno dei seguenti valori:
"KNOWN_CAPTURING", "KNOWN_CONTROLLING","UNKNOWN_CAPTURING" o
"UNKNOWN_CONTROLLING", significa che sul dispositivo sono in esecuzione app che
potrebbero acquisire lo schermo o controllare il dispositivo.
Correzione
Puoi mostrare la finestra di dialogo CLOSE_ALL_ACCESS_RISK per chiedere all'utente di chiudere tutte le app che potrebbero acquisire lo schermo o controllare il dispositivo. Se l'utente tocca il pulsante Close all, tutte queste app vengono chiuse sul dispositivo.
Esempio di UX
GET_INTEGRITY (codice tipo 4)
Problema relativo all'esito
Questa finestra di dialogo è appropriata per uno dei seguenti problemi:
Integrità del dispositivo debole: quando
deviceRecognitionVerdictnon contieneMEETS_DEVICE_INTEGRITY, il dispositivo potrebbe non essere un dispositivo Android originale e certificato. Ciò può accadere, ad esempio, se il bootloader del dispositivo è sbloccato o se il sistema operativo Android caricato non è un'immagine del produttore certificata.Accesso non autorizzato:
appLicensingVerdict: "UNLICENSED". Ciò significa che l'account utente non ha diritto alla tua app, il che può accadere se l'utente l'ha eseguita tramite sideload o l'ha acquisita da un app store diverso da Google Play.App manomessa:
appRecognitionVerdict: "UNRECOGNIZED_VERSION". Ciò significa che il file binario della tua app è stato modificato o non è una versione riconosciuta da Google Play.Eccezioni lato client: quando si verifica un'eccezione correggibile durante una richiesta API dell'API Integrity. Le eccezioni correggibili sono eccezioni dell'API Integrity con codici di errore come
PLAY_SERVICES_VERSION_OUTDATED,NETWORK_ERROR,PLAY_SERVICES_NOT_FOUND, e così via. Puoi utilizzare il metodoexception.isRemediable()per verificare se una finestra di dialogo può correggere un'eccezione.
Correzione
La finestra di dialogo GET_INTEGRITY è progettata per semplificare l'esperienza dell'utente gestendo più passaggi di correzione in un unico flusso continuo. In questo modo, l'utente non deve interagire con più finestre di dialogo separate per risolvere problemi diversi.
Quando richiedi la finestra di dialogo, questa rileva automaticamente quali problemi relativi all'esito di destinazione sono presenti e fornisce i passaggi di correzione appropriati. Ciò significa che una singola richiesta di finestra di dialogo può risolvere più problemi contemporaneamente, tra cui:
- Integrità del dispositivo: se viene rilevato un problema di integrità del dispositivo, la finestra di dialogo
guiderà l'utente a migliorare lo stato di sicurezza del dispositivo per soddisfare i
requisiti per un esito
MEETS_DEVICE_INTEGRITY. - Integrità dell'app: se vengono rilevati problemi come l'accesso non autorizzato o la manomissione dell'app, la finestra di dialogo indirizzerà gli utenti ad acquisire l'app dal Play Store per risolverli.
- Eccezioni lato client: la finestra di dialogo verifica e tenta di risolvere eventuali problemi sottostanti che hanno causato un'eccezione dell'API Integrity. Ad esempio, potrebbe chiedere all'utente di aggiornare una versione obsoleta di Google Play Services.
Esempio di UX
GET_STRONG_INTEGRITY (codice tipo 5)
Problema relativo all'esito
Questa finestra di dialogo è progettata per risolvere tutti gli stessi problemi di
GET_INTEGRITY, con la funzionalità aggiuntiva di risolvere i problemi che impediscono a un dispositivo
di ricevere un esito MEETS_STRONG_INTEGRITY e risolvere i problemi relativi all'esito di Play Protect.
Correzione
GET_STRONG_INTEGRITY è progettata per semplificare l'esperienza dell'utente gestendo più passaggi di correzione in un unico flusso continuo. La finestra di dialogo verifica automaticamente la presenza di problemi di integrità applicabili all'indirizzo, tra cui:
- Integrità del dispositivo: se viene rilevato un problema di integrità del dispositivo, la finestra di dialogo
guiderà l'utente a migliorare lo stato di sicurezza del dispositivo per soddisfare i
requisiti per un esito
MEETS_STRONG_INTEGRITY. Stato di Play Protect: se
playProtectVerdictindica un problema, la finestra di dialogo guiderà l'utente a risolverlo:- Se Play Protect è disattivato (
playProtectVerdict == POSSIBLE_RISK), la finestra di dialogo chiederà all'utente di attivarlo ed eseguire una scansione di tutte le app sul dispositivo. - Se vengono rilevate app dannose (
playProtectVerdict == MEDIUM_RISKoHIGH_RISK), la finestra di dialogo indirizzerà l'utente a disinstallarle utilizzando Google Play Protect.
- Se Play Protect è disattivato (
Integrità dell'app: se vengono rilevati problemi come l'accesso non autorizzato o la manomissione dell'app, la finestra di dialogo chiederà all'utente di acquisire l'app dal Play Store per risolvere il problema.
Eccezioni lato client: la finestra di dialogo tenta anche di risolvere eventuali problemi sottostanti che hanno causato un'eccezione dell'API Integrity. Ad esempio, potrebbe chiedere all'utente di attivare Google Play Services se risulta disattivato. Le eccezioni correggibili sono eccezioni dell'API Integrity con codici di errore come
PLAY_SERVICES_VERSION_OUTDATED,NETWORK_ERRORoPLAY_SERVICES_NOT_FOUND. Puoi utilizzare il metodoexception.isRemediable()per verificare se una finestra di dialogo può correggere un errore.
Esempio di UX