Compatibilidad con actualizaciones integradas en la app (Unreal Engine)

En esta guía, se describe cómo admitir las actualizaciones dentro de la app en tu app con Unreal Engine. Hay guías separadas para casos en los que tu implementación usa el lenguaje de programación Kotlin o Java, y otros en los que ella usa código nativo (C/C++) o Unity.

Descripción general del SDK de Unreal Engine

La API de Play In-App Updates forma parte de la familia del SDK de Play Core. La API de Unreal Engine ofrece una clase UInAppUpdatesManager para controlar la comunicación entre tu app y la API de Play. Después de realizar una solicitud, tu app puede verificar el estado de la solicitud con EAppUpdateErrorCode.

Versiones de Unreal Engine compatibles

El complemento admite Unreal Engine 5.0 y todas las versiones posteriores.

Cómo configurar tu entorno de desarrollo

Nota: Si ya usaste los complementos de Opiniones en la aplicación o Actualizaciones en la aplicación en Unreal Engine, puedes ir al paso final.

1. Descarga el complemento de Unreal Engine para Play desde el repositorio de GitHub.

2. Copia la carpeta GooglePlay dentro de la carpeta Plugins en tu proyecto de Unreal Engine.

3. Abre tu proyecto de Unreal Engine y haz clic en Editar → Plugins.

4. Busca Google Play y marca la casilla de verificación Habilitada.

5. Reinicia el proyecto del juego y activa una compilación.

6. Abre el archivo Build.cs de tu proyecto y agrega el módulo PlayInAppUpdates a PublicDependencyModuleNames:

   using UnrealBuildTool;
   
   public class MyGame : ModuleRules
   {
     public MyGame(ReadOnlyTargetRules Target) : base(Target)
     {
       // ...
   
       PublicDependencyModuleNames.Add("PlayInAppUpdates");
   
       // ...
     }
   }
   

Cómo comprobar la disponibilidad de actualizaciones

Antes de solicitar una actualización, verifica si hay una disponible para tu app. Usa UInAppUpdatesManager::RequestInfo para verificar si hay una actualización:

MyClass.h

void MyClass::OnRequestInfoOperationCompleted(
  EAppUpdateErrorCode ErrorCode,
  UAppUpdateInfo* UpdateInfo)
{
  // Check the resulting error code.
  if (ErrorCode == EAppUpdateErrorCode::AppUpdate_NO_ERROR)
  {
    // Check AppUpdateInfo's UpdateAvailability, UpdatePriority,
    // IsUpdateTypeAllowed(), ... and decide whether to ask the user
    // to start an in-app update.
  }
}

MyClass.cpp

void MyClass::CheckForUpdateAvailability()
{
  // Create a delegate to bind the callback function.
  FRequestInfoOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestInfoOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestInfoOperationCompleted);

  // Initiate the request info operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->RequestInfo(Delegate);
}

La instancia de UAppUpdateInfo que se muestra contiene el estado de disponibilidad de la actualización. Si una actualización integrada en la app ya está en curso, la instancia también informa el estado de esa actualización.

Cómo verificar la obsolescencia de las actualizaciones

Además de comprobar si hay actualizaciones disponibles, te recomendamos que verifiques cuánto tiempo pasó desde que el usuario recibió una notificación sobre una actualización a través de Google Play Store. Esto puede ayudarte a decidir si debes iniciar una actualización flexible o una actualización inmediata. Por ejemplo, podrías esperar unos días antes de notificar al usuario con una actualización flexible y, luego, solicitar una actualización inmediata.

Usa UAppUpdateInfo:GetClientVersionStalenessDays para verificar la cantidad de días desde que la actualización estuvo disponible en Play Store:

int32 ClientVersionStalenessDays = UpdateInfo->GetClientVersionStalenessDays();

Cómo verificar la prioridad de las actualizaciones

La API de Google Play Developer te permite establecer la prioridad de cada actualización. Esto le permite a tu app decidir con qué intensidad recomendar una actualización al usuario. Por ejemplo, considera la siguiente estrategia para establecer la prioridad de actualización:

• Mejoras menores en la IU: Actualización de baja prioridad. No solicites una actualización flexible ni una actualización inmediata.
• Mejoras en el rendimiento: actualización de prioridad media. Solicita una actualización flexible.
• Actualización crítica de seguridad: actualización de prioridad alta. Requiere una actualización inmediata.

Para determinar la prioridad, Google Play usa un valor entero entre 0 y 5, en el que 0 es la prioridad predeterminada y 5 es la más alta. A fin de establecer la prioridad para una actualización, usa el campo inAppUpdatePriority en Edits.tracks.releases en la API de Google Play Developer. Se considerará que todas las versiones agregadas en la original tendrán establecida la misma prioridad que esta última. Solo se puede establecer la prioridad al momento de lanzar una versión nueva; no se puede cambiar más tarde.

Establece la prioridad con la API de Google Play Developer como se describe en la documentación de la API de Play Developer. La prioridad de la actualización integrada en la app debe especificarse en el recurso Edit.tracks que se pasa en el método Edit.tracks: update. En el siguiente ejemplo, se muestra cómo lanzar una app con código de versión 88 y inAppUpdatePriority 5:

{
  "releases": [{
      "versionCodes": ["88"],
      "inAppUpdatePriority": 5,
      "status": "completed"
  }]
}

En el código de tu app, puedes verificar el nivel de prioridad de una actualización determinada con UAppUpdateInfo::UpdatePriority:

int32 Priority = UpdateInfo->GetPriority();

Cómo iniciar una actualización

Después de confirmar que hay una actualización disponible, puedes solicitarla con UInAppUpdatesManager::StartUpdate. Antes de solicitar una actualización, asegúrate de tener un objeto UAppUpdateInfo actualizado. También debes crear un objeto UAppUpdateOptions para configurar el flujo de actualización.

En el siguiente ejemplo, se crea un objeto UAppUpdateOptions para un flujo de actualización inmediato:

// Creates an UAppUpdateOptions defining an immediate in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_IMMEDIATE);

En el siguiente ejemplo, se crea un objeto UAppUpdateOptions para un flujo de actualización flexible:

// Creates an UAppUpdateOptions defining a flexible in-app
// update flow and its parameters.
UAppUpdateOptions* Options = NewObject<UAppUpdateOptions>();
Options->CreateOptions(EAppUpdateType::AppUpdate_TYPE_FLEXIBLE);

El objeto UAppUpdateOptions también contiene una función IsAssetPackDeletionAllowed que muestra si la actualización puede borrar paquetes de recursos en caso de que el almacenamiento del dispositivo sea limitado. Este campo se establece en false de forma predeterminada, pero puedes configurarlo con UAppUpdateOptions::SetAssetPackDeletionAllowed para establecerlo en true en su lugar:

// Sets the AssetPackDeletionAllowed field to true.
Options->SetAssetPackDeletionAllowed(true);

Nota: Usa la opción de la API de AllowAssetPackDeletion con cuidado para evitar borrar recursos por accidente. Antes de configurar esta opción en true, debes verificar si UAppUpdateInfo::IsUpdateTypeAllowed con la opción AllowAssetPackDeletion establecida en false.

Los pasos siguientes dependerán de si solicitas una actualización flexible o una actualización inmediata.

Cómo manejar una actualización flexible

Una vez que tengas un objeto UAppUpdateInfo actualizado y un objeto UAppUpdateOptions configurado correctamente, puedes llamar a UInAppUpdatesManager::StartUpdate para solicitar un flujo de actualización.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

// .cpp
void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Para un flujo de actualización flexible, debes activar la instalación de la actualización de la app una vez que la descarga finalice correctamente. Para ello, llama a InAppUpdatesManager::CompleteUpdate, como se muestra en el siguiente ejemplo:

MyClass.h

void MyClass::OnCompleteUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::CompleteFlexibleUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnCompleteUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnCompleteUpdateOperationCompleted);

  // Initiate the complete update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->CompleteUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Cómo manejar una actualización inmediata

Una vez que tengas un objeto UAppUpdateInfo actualizado y un objeto UAppUpdateOptions configurado correctamente, puedes llamar a InAppUpdatesManager::StartUpdate para solicitar un flujo de actualización.

MyClass.h

void MyClass::OnStartUpdateOperationCompleted(EAppUpdateErrorCode ErrorCode)
{
  // ...
}

MyClass.cpp

void MyClass::StartUpdate()
{
  // Create a delegate to bind the callback function.
  FUpdateOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnStartUpdateOperationCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnStartUpdateOperationCompleted);

  // Initiate the start update operation, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UInAppUpdatesManager>()
    ->StartUpdate(UpdateInfo, UpdateOptions, Delegate);
}

Para obtener un flujo de actualización inmediata, Google Play muestra un cuadro de diálogo de confirmación del usuario. Cuando el usuario acepta la solicitud, Google Play descarga e instala automáticamente la actualización, luego, reinicia la app a la versión actualizada si la instalación se realizó correctamente.

Administración de errores

En esta sección, se describen las soluciones de errores comunes.

• Si UInAppUpdatesManager::StartUpdate muestra un error AppUpdate_INVALID_REQUEST, significa que UAppUpdateInfo no es válida. Asegúrate de que el objeto UAppUpdateInfo que se muestra desde UInAppUpdatesManager::RequestInfo no sea nulo antes de iniciar el flujo de actualización.
• Si UInAppUpdatesManager::StartUpdate muestra el error AppUpdate_NOT_ALLOWED, significa que el objeto UAppUpdateOptions indica un tipo de actualización que no se permite para la actualización disponible. Verifica si el objeto UAppUpdateInfo indica que se permite el tipo de actualización seleccionado antes de iniciar el flujo de actualización.

Próximos pasos

Prueba las actualizaciones en la app para verificar que la integración funcione correctamente.