Configurar flavors de Flutter para iOS y macOS

Esta guía muestra cómo crear flavors de Flutter para una aplicación de iOS o macOS.

Un flavor de Flutter es básicamente una colección de configuraciones que definen cómo se debe compilar y ejecutar una versión específica de tu aplicación. Por ejemplo, un flavor podría determinar qué icono, nombre de aplicación, clave de API, indicador de característica (feature flag) y nivel de registro se asocian con una versión específica de tu aplicación.

Si deseas crear flavors de Flutter para una aplicación de iOS, deberás hacerlo en Xcode. Xcode no tiene un concepto llamado "flavor". En su lugar, deberás configurar algo llamado un esquema (scheme) y adjuntar configuraciones personalizadas al mismo.

A continuación se ilustra un ejemplo de dos flavors de Flutter (staging, production) como esquemas de Xcode con configuraciones de Xcode personalizadas asignadas a ellos:

Los siguientes pasos muestran cómo configurar dos esquemas de Xcode llamados staging y production para tu proyecto Flutter de iOS. También puedes usar estos pasos para configurar un proyecto de macOS reemplazando cualquier referencia a iOS con macOS.

Para un flujo de trabajo fluido, hemos comenzado con un nuevo proyecto de Flutter llamado flavors_example, pero siempre puedes comenzar con un proyecto existente.

1. Crea un nuevo proyecto Flutter llamado flavors_example.

   consola

   $ flutter create flavors_example
   

   content_copy

2. Abre el espacio de trabajo de Xcode predeterminado para la versión de iOS del proyecto flavors_example.

   consola

   $ cd flavors_example && open ios/Runner.xcworkspace
   

   content_copy

3. Abre el proyecto flavors_example en el navegador del proyecto de Xcode:

   • Abre el navegador del proyecto (View > Navigators > Project).

   • En el navegador del proyecto, en la parte superior, selecciona Runner.

4. Crear esquemas en Xcode:

   • Abre la ventana New Scheme (Product > Scheme > New Scheme).

   • En el campo Target, selecciona Runner.

   • En la casilla Name, ingresa staging.

   • Haz clic en Okay para añadir el nuevo esquema.

   • Repite los pasos anteriores para un esquema llamado production.

   • Cuando termines, verifica que tengas los siguientes esquemas:

     

5. Crear configuraciones para los esquemas en Xcode:

   • En el navegador del proyecto, selecciona Runner.

   • En la ventana principal bajo PROJECT, selecciona Runner.

   • Abre la pestaña Info si no está abierta.

   • Ve a la sección Configurations y añade nuevas configuraciones Debug.

     • Haz clic en +, selecciona Duplicate "Debug" configuration y nombra la nueva configuración Debug-staging.
     • Haz clic en +, selecciona Duplicate "Debug" configuration y nombra la nueva configuración Debug-production.

   • Repite el paso anterior para las configuraciones Release y las Profile.

   • Cuando termines, verifica que tengas los siguientes esquemas:

     

6. Asignar las configuraciones a los esquemas en Xcode:

   • Abre la ventana Manage Schemes (Product > Scheme > Manage Schemes).

   • Selecciona el esquema staging y edítalo.

   • En las siguientes pestañas, actualiza el campo Build Configuration de la siguiente manera:

     • Run: Debug-staging
     • Test: Debug-staging
     • Profile: Profile-staging
     • Analyze: Debug-staging
     • Archive: Release-staging

   • Haz clic en Close.

   • Repite los pasos anteriores para el esquema production.

7. Si estás trabajando con un proyecto Flutter preexistente que tiene al menos un Podfile, actualízalo. Para obtener más información, consulta Actualizar Podfiles.

8. Para asegurarte de que has configurado todo correctamente, ejecuta tu aplicación en los nuevos esquemas en Xcode. No verás ninguna diferencia porque los ajustes de configuración no han cambiado, pero sí quieres asegurarte de que la aplicación pueda ejecutarse.

   • Selecciona el esquema staging (Product > Schemes > staging).

   • A la derecha de staging en la barra de herramientas, selecciona el dispositivo iOS en el que deseas realizar la prueba. En el siguiente ejemplo, el dispositivo es iPhone 16 Pro.

     

   • Ejecuta el esquema de la aplicación (Product > Run).

   • Repite los pasos anteriores para el esquema production.

9. Si todo se ejecuta, estás listo para personalizar tus configuraciones. Para obtener más información, consulta Personalizar las configuraciones.

Después de haber creado los esquemas para una aplicación de iOS en Xcode, puedes iniciar un esquema específico a través de Xcode o Flutter. También puedes usar estos pasos para iniciar un proyecto de macOS reemplazando cualquier referencia a iOS con macOS.

Puedes iniciar un esquema de Xcode en modo Debug con la CLI de Flutter utilizando los siguientes pasos:

1. En tu IDE, inicia el simulador de iOS.

2. En la consola, navega al directorio flavors_example e ingresa el siguiente comando:

   consola

   $ flutter run --flavor <xcode_scheme_name>
   

   content_copy
   • <xcode_scheme_name>: Reemplaza esto con el nombre de tu esquema de Xcode (por ejemplo, staging o production).

   Ejemplo:

   consola

   $ flutter run --flavor staging
   

   content_copy

1. Importa la biblioteca services: Para acceder a la constante appFlavor, agrega la siguiente importación a tu archivo Dart:

   dart

   import 'package:flutter/services.dart';
   

   content_copy

2. Comprueba el valor del flavor: Utiliza la constante appFlavor en la lógica de tu aplicación (a menudo en main()) para manejar configuraciones específicas del flavor:

   dart

   void main() {
     // appFlavor will match the name of the Xcode scheme
     if (appFlavor == 'production') {
       // Logic for production environment
       Config.apiUrl = 'https://api.flavors_example.com';
     } else if (appFlavor == 'staging') {
       // Logic for staging environment
       Config.apiUrl = 'https://staging.api.flavors_example.com';
     }
   ​
     runApp(const MyApp());
   }
   

   content_copy

Puedes iniciar un esquema específico en Xcode utilizando los siguientes pasos:

1. Selecciona el esquema que deseas probar (Product > Schemes > Choose scheme).

2. Junto al nombre del esquema en la barra de herramientas, selecciona el dispositivo en el que deseas realizar la prueba.

3. Ejecuta el esquema para tu aplicación (Product > Run).

Después de agregar esquemas de Xcode, puedes personalizarlos para tu aplicación de iOS. También puedes usar estos pasos para configurar un proyecto de macOS reemplazando cualquier referencia a iOS con macOS.

Si tienes múltiples esquemas, un nombre de aplicación distinto puede identificar rápidamente qué esquema está utilizando tu aplicación desplegada.

Los siguientes pasos muestran cómo agregar nombres de visualización de aplicaciones distintos en Xcode para dos esquemas llamados staging y production en un proyecto llamado flavors_example.

1. Crear configuraciones definidas por el usuario en Xcode:

   • Abre el navegador del proyecto (View > Navigators > Project).

   • En el navegador del proyecto, en la parte superior, selecciona Runner.

   • En la ventana principal bajo TARGETS, selecciona Runner.

   • Abre la pestaña Build Settings.

   • A la izquierda de la pestaña Basic, haz clic en + y selecciona Add User-Defined Setting.

   • Crea una configuración llamada APP_DISPLAY_NAME.

   • Despliega la configuración APP_DISPLAY_NAME.

   • Asigna los siguientes valores a las siguientes claves:

     • Debug-production: Flavors prod
     • Debug-staging: Flavors staging
     • Profile-production: Flavors prod
     • Profile-staging: Flavors staging
     • Release-production: Flavors prod
     • Release-staging: Flavors staging

2. Actualiza Info.plist en Xcode:

   • En el navegador del proyecto, selecciona Runner > Runner > Info para abrir flavor_test/ios/Runner/Info.plist.

   • Bajo Information Property List, busca la siguiente clave y actualiza su valor:

     • Key: CFBundleDisplayName
     • Value: $(APP_DISPLAY_NAME)

3. Inicia la aplicación para cada esquema (staging, production) y asegúrate de que el nombre de visualización de la aplicación haya cambiado para cada uno. Para iniciar un esquema, consulta los pasos en Iniciar un esquema de Xcode.

Si tienes múltiples esquemas, un icono distinto para cada configuración puede ayudarte a identificar rápidamente qué esquema está utilizando tu aplicación desplegada.

Los siguientes pasos muestran cómo agregar un icono distinto en Xcode para dos esquemas llamados staging y production en un proyecto de iOS llamado flavors_example.

1. Prepara tus iconos:

   • Diseña tu icono de staging y tu icono de production en la herramienta de diseño de tu elección.

   • Genera versiones del icono de staging y del icono de production en los tamaños que necesites. Guárdalos en formato PNG.

2. Añade los iconos a tu proyecto de Xcode:

   • Abre el navegador del proyecto (View > Navigators > Project).

   • En el navegador del proyecto, selecciona Runner > Runner > Assets para abrir la ventana Assets.

   • Completa los siguientes pasos para el icono de staging:

     • Haz clic en + > iOS > iOS App icon.

     • Nombra el icono AppIcon-staging.

     • Arrastra tus iconos de staging a la ventana AppIcon-staging y asegúrate de que los iconos estén asignados a los tamaños correctos.

   • Repite el paso anterior para el icono de production.

3. Conecta los iconos a tus esquemas:

   • Abre el navegador del proyecto.

   • En la ventana principal bajo TARGETS, selecciona Runner.

   • Abre la pestaña General si no está abierta.

   • Ve a la sección Apps Icons and Launch Screen y despliégala.

   • A la derecha del campo App icon, haz clic en + y actualiza los campos de la siguiente manera:

     • Debug-staging: AppIcon-staging
     • Profile-staging: AppIcon-staging
     • Release-staging: AppIcon-staging
     • Debug-production: AppIcon-production
     • Profile-production: AppIcon-production
     • Release-production: AppIcon-production

4. Inicia la aplicación para cada esquema (staging, production) y asegúrate de que el icono de la aplicación haya cambiado para cada uno. Para iniciar un esquema, consulta los pasos en Iniciar un esquema de Xcode.

Un identificador de bundle es un identificador único para tu aplicación en las plataformas de Apple. Si estás utilizando múltiples esquemas de Xcode como flavors de Flutter, puedes hacer que Apple trate cada esquema como una aplicación independiente. Para hacer esto, debes asignar un identificador de bundle diferente a cada esquema. Esto te permite probar nuevas funciones o correcciones de errores en una versión de la aplicación (por ejemplo, staging) sin afectar a otra versión de la aplicación (por ejemplo, production).

Los siguientes pasos muestran cómo establecer un identificador de bundle único para dos esquemas de Xcode llamados staging y production en un proyecto de iOS llamado flavors_example.

1. En Xcode, abre el navegador del proyecto (View > Navigators > Project).

2. En la ventana principal bajo TARGETS, selecciona Runner.

3. Abre la pestaña Build Settings.

4. Navega a la sección Packaging.

5. Despliega la configuración Product Bundle Identifier para ver las diferentes configuraciones de compilación.

6. Para la configuración de compilación de cada esquema, establece el identificador de bundle deseado. Por ejemplo:

   • Debug-staging, Profile-staging, Release-staging:

     com.example.flavorsExample.staging

   • Debug, Profile, Release, Debug-production, Profile-production, Release-production:

     com.example.flavorsExample

7. Asegúrate de que estos identificadores de bundle estén incluidos en tu App ID y que tu App ID esté registrado en tu cuenta de Apple Developer.

Si tienes assets que solo se utilizan en un flavor específico en tu aplicación, puedes configurarlos para que solo se empaqueten en tu aplicación al iniciar ese flavor. Esto evita que el tamaño de tu app bundle se infle con assets no utilizados. Para empaquetar assets para cada flavor, añade el subcampo flavors al campo assets en el pubspec de tu proyecto. Para obtener más información, consulta el campo assets en Opciones de pubspec de Flutter.

Si estás creando nuevos esquemas de Xcode para un proyecto Flutter de iOS y tienes un Podfile de iOS en un proyecto Flutter existente, debes actualizar el Podfile de iOS de Flutter para que coincida con los cambios que realizaste en Xcode.

Los siguientes pasos muestran cómo actualizar tu Podfile de iOS para incluir dos nuevos esquemas de Xcode llamados staging y production en un proyecto de Flutter llamado flavors_example. También puedes usar estos pasos para actualizar un proyecto de macOS reemplazando cualquier referencia a iOS con macOS.

1. En tu IDE, abre el archivo ios/Podfile.

2. Realiza las siguientes actualizaciones y guarda tus cambios.

   flavors_example/ios/Podfile

   ruby

   project 'Runner', {
     ...
     'Debug' => :debug,
     'Debug-staging' => :debug,
     'Debug-production' => :debug,
     'Profile' => :release,
     'Profile-staging' => :release,
     'Profile-production' => :release,
     'Release' => :release,
     'Release-staging' => :release,
     'Release-production' => :release,
     ...
   

   content_copy

Puedes usar configuraciones de compilación para controlar tu proceso de compilación de iOS desde la compilación y vinculación hasta la depuración y distribución. Una forma en la que puedes usar las configuraciones de compilación con los flavors de Flutter es asignar esas configuraciones de compilación a las configuraciones de compilación de Xcode. Por ejemplo, es posible que desees asignar diferentes URL de API a Debug-staging y Debug-production. Por ejemplo:

# Debug-staging build settings
API_BASE_URL = staging.flavors.com/api

# Debug-production build settings
API_BASE_URL = flavors.com/api

Si deseas añadir configuraciones de compilación adicionales para una configuración de compilación específica, consulta Añadir un archivo de configuración de compilación a tu proyecto de Apple.

Este documento contiene algunas configuraciones de esquemas de Xcode comunes, pero hay muchas más que puedes aplicar. Para aprender sobre ellas, consulta Personalizar los esquemas de compilación para un proyecto.

Para obtener más información sobre la creación y el uso de flavors, consulta los siguientes recursos:

• Cómo configurar Flutter y Firebase con múltiples flavors usando la CLI de FlutterFire
• Compilar flavors en Flutter (Android e iOS) con diferentes proyectos de Firebase por flavor Ready to Go