Compatibilidad con actualizaciones integradas en la app (Unreal Engine)

En esta guía, se describe cómo admitir las actualizaciones de la app integradas en tu app con Unreal Engine. Hay guías separadas para casos en los que tu implementación usa los lenguajes 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 actualizaciones integradas en la app de Play forma parte de la familia del SDK de Play Core. La API para Unreal Engine ofrece una clase UInAppUpdatesManager para controlar la comunicación entre tu app y la API de Play. Después de que se realiza una solicitud, tu app puede verificar el estado de la solicitud con EAppUpdateErrorCode.

Versiones compatibles de Unreal Engine

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

Configura tu entorno de desarrollo

  1. Descarga el complemento de Play para Unreal Engine 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 Edit → Plugins.

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

  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 alguna disponible para tu app. Usa UInAppUpdatesManager::RequestInfo para comprobar 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 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 que transcurrieron 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 permite que tu app decida con qué nivel de urgencia 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 de la app integrada 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 el código de versión 88 y el 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 indica si la actualización puede borrar los paquetes de recursos en caso de que el dispositivo tenga almacenamiento limitado. Este campo se establece como false de forma predeterminada, pero puedes usar UAppUpdateOptions::SetAssetPackDeletionAllowed para establecerlo en true:

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

Los siguientes pasos dependen 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, podrás 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, podrás 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 devuelve un error AppUpdate_INVALID_REQUEST, significa que UAppUpdateInfo no es válido. 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 devuelve el error AppUpdate_NOT_ALLOWED, significa que el objeto UAppUpdateOptions indica un tipo de actualización que no está permitido para la actualización disponible. Antes de iniciar el flujo de actualización, verifica si el objeto UAppUpdateInfo indica que se permite el tipo de actualización seleccionado.

Próximos pasos

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