DEV Community: Wesley Oliveira

White-Label em Flutter: duas filosofias, três técnicas

Wesley Oliveira — Mon, 28 Sep 2026 14:06:55 +0000

Se você já precisou publicar o "mesmo app" para 5, 10 ou 20 marcas diferentes, já bateu de frente com a pergunta: onde mora a diferença entre um tenant e outro?

TL;DR

🏗️ Flavors: build por tenant, isolamento total (applicationId, ícone), CI cresce com cada marca.
📁 Pasta + script: mais simples que flavors, boa quando a diferença é só tema/assets.
🌐 Config por endpoint: 1 build para todos, muda sem rebuild, mas depende de rede e de isolamento no backend.
Na prática, a maioria combina as três — veja o guia de decisão no fim.

Existem duas filosofias possíveis:

Build-time: cada tenant vira um build separado. A diferença é resolvida antes do app existir, em tempo de compilação.
Runtime: existe um único build. A diferença é resolvida depois que o app já está rodando, buscando configuração de fora.

Dentro da filosofia build-time cabem duas técnicas bem diferentes na prática — flavors e pasta por tenant com script de troca. E a filosofia runtime geralmente se resolve com configuração buscada de um endpoint. Este artigo cobre as três, com código, trade-offs reais e um guia de quando usar cada uma.

Não existe "a certa". Existe a certa para o seu número de tenants, sua frequência de mudança de marca e sua tolerância a builds manuais.

Visão geral rápida

	Flavors	Pasta por tenant + script	Endpoint de config
Filosofia	Build-time	Build-time	Runtime
Quantos builds/artefatos	1 por tenant	1 por tenant	1 (todos os tenants)
Precisa rebuild pra mudar cor/logo	Sim	Sim	Não
Funciona offline	Sim	Sim	Só com cache local
Novo tenant sem tocar em código	Não	Parcialmente	Sim, se só muda tema/feature flag
Risco de configuração vazar entre tenants	Baixo (isolado no bundle)	Baixo (isolado no bundle)	Precisa de cuidado no backend
Esforço de CI/CD	Alto (N pipelines)	Médio (1 pipeline + parâmetro)	Baixo (1 pipeline)
Bom para	Poucos tenants, diferenças profundas (ícone, nome do app, permissões nativas)	Poucos a médios tenants, times pequenos, sem infra de backend dedicada	Muitos tenants, mudanças de marca frequentes, mesma regra de negócio

Na prática, a maioria dos projetos maduros acaba combinando build-time para o que é fixo (application ID, nome do app, ícone, permissões nativas) com runtime para o que muda com frequência (cores, textos, feature flags). Mas vamos por partes.

1. Build-time: Flavors

Flavors (ou product flavors, no Android; schemes + configurations, no iOS) fazem o Flutter gerar builds distintos a partir da mesma base de código, cada um com seu próprio applicationId/bundle identifier, ícone, nome e ponto de entrada.

Estrutura

lib/
  main_tenant_a.dart
  main_tenant_b.dart
  main_common.dart        # bootstrap compartilhado
android/
  app/
    build.gradle           # flavorDimensions + productFlavors
ios/
  Runner.xcodeproj         # schemes + xcconfig por tenant

Android — `android/app/build.gradle`

android {
    flavorDimensions "tenant"
    productFlavors {
        tenantA {
            dimension "tenant"
            applicationId "com.example.tenanta"
            resValue "string", "app_name", "Tenant A"
        }
        tenantB {
            dimension "tenant"
            applicationId "com.example.tenantb"
            resValue "string", "app_name", "Tenant B"
        }
    }
}

iOS

No iOS não existe "flavor" nativo — a prática comum é criar uma Configuration (Debug-TenantA, Release-TenantA, etc.) e um Scheme por tenant, cada um apontando para um .xcconfig próprio com PRODUCT_BUNDLE_IDENTIFIER, PRODUCT_NAME e o AppIcon correspondente.

Entry point compartilhado

// lib/main_common.dart
Future<void> bootstrap(TenantConfig config) async {
  runApp(MyApp(config: config));
}

// lib/main_tenant_a.dart
void main() {
  bootstrap(TenantConfig.tenantA);
}

// lib/main_tenant_b.dart
void main() {
  bootstrap(TenantConfig.tenantB);
}

Rodando e buildando

flutter run --flavor tenantA -t lib/main_tenant_a.dart
flutter build apk --flavor tenantA -t lib/main_tenant_a.dart
flutter build ipa --flavor tenantA -t lib/main_tenant_a.dart

Trade-offs

A favor:

Isolamento real. applicationId, ícone, nome e permissões nativas (AndroidManifest.xml, Info.plist) podem divergir de verdade entre tenants — coisa que uma configuração remota não alcança.
Cada tenant é um artefato de loja independente, o que é exigido quando cada marca precisa aparecer com seu próprio nome na App Store/Play Store.
Funciona 100% offline, porque tudo já está compilado no binário.

Contra:

CI/CD cresce linearmente com o número de tenants. Com 15 tenants, são 15 pipelines de build (ou 1 pipeline com matriz de 15 combinações).
Mudar uma cor ou um texto exige rebuild, novo upload e nova aprovação de loja.
Acima de ~10-15 tenants o build.gradle e os schemes do Xcode viram um arquivo difícil de manter.

Use quando: o número de tenants é baixo (tipicamente até 10-15), as diferenças vão além de tema (ícone, nome do app, application ID, permissões nativas) e builds separados por marca são um requisito de negócio, não um detalhe técnico.

2. Build-time: pasta por tenant + script de troca

Uma variação mais simples de manter que flavors quando a diferença entre tenants é majoritariamente assets e configuração, não applicationId nem permissões nativas.

Estrutura

tenants/
  tenant_a/
    assets/
      logo.png
      splash.png
    theme.json
  tenant_b/
    assets/
      logo.png
      splash.png
    theme.json
assets/
  active/            # gerado pelo script, git-ignored
    logo.png
    splash.png
    theme.json

Script de troca

#!/usr/bin/env bash
# scripts/select_tenant.sh
set -euo pipefail

TENANT="${1:?Uso: select_tenant.sh <nome-do-tenant>}"
SRC="tenants/$TENANT"
DEST="assets/active"

if [ ! -d "$SRC" ]; then
  echo "Tenant '$TENANT' não encontrado em tenants/"
  exit 1
fi

rm -rf "$DEST"
mkdir -p "$DEST"
cp -R "$SRC/assets/." "$DEST/"
cp "$SRC/theme.json" "$DEST/theme.json"

echo "Tenant ativo: $TENANT"

chmod +x scripts/select_tenant.sh
./scripts/select_tenant.sh tenant_a
flutter build apk

`pubspec.yaml`

flutter:
  assets:
    - assets/active/

Lendo o tema em runtime (mas ainda dentro do bundle)

class ThemeLoader {
  static Future<ThemeData> load() async {
    final raw = await rootBundle.loadString('assets/active/theme.json');
    final json = jsonDecode(raw) as Map<String, dynamic>;
    return ThemeData(
      primaryColor: Color(int.parse(json['primaryColor'] as String)),
      // ...
    );
  }
}

Trade-offs

A favor:

Muito mais simples de configurar que flavors — sem tocar em Gradle nem em Xcode.
Um único pipeline de CI, parametrizado pelo nome do tenant.
Onboarding de tenant novo é criar uma pasta e preencher theme.json, sem escrever código.

Contra:

Ainda gera um binário por tenant — não resolve o problema de "1 app, N marcas" em runtime.
Se applicationId e permissões nativas também precisam mudar por tenant, o script sozinho não cobre; você acaba combinando com flavors de qualquer forma.
Fácil esquecer de rodar o script antes do build errado e publicar o tenant errado — vale um passo de CI que falha se assets/active estiver vazio ou não bater com o parâmetro do build.

Use quando: os tenants diferem principalmente em tema, logo e textos, o time é pequeno, e configurar Gradle flavors + Xcode schemes para cada marca nova é mais trabalho do que o problema justifica.

3. Runtime: configuração por endpoint

Aqui a filosofia muda: existe um único build, publicado uma vez, e o tenant é resolvido depois que o app já está instalado no dispositivo.

Como o app descobre "quem ele é"

Algumas estratégias comuns, sozinhas ou combinadas:

Domínio de login: o usuário digita empresa.suaplataforma.com ou seleciona a empresa numa tela inicial.
Deep link / QR code de convite: o link de instalação já carrega o tenant_id.
Login primeiro, tenant depois: o backend de autenticação retorna o tenant_id junto do token.

Buscando e aplicando a configuração

class TenantConfig {
  final String tenantId;
  final Color primaryColor;
  final String logoUrl;
  final Map<String, bool> features;

  TenantConfig({
    required this.tenantId,
    required this.primaryColor,
    required this.logoUrl,
    required this.features,
  });

  factory TenantConfig.fromJson(Map<String, dynamic> json) {
    return TenantConfig(
      tenantId: json['tenantId'] as String,
      primaryColor: Color(int.parse(json['primaryColor'] as String)),
      logoUrl: json['logoUrl'] as String,
      features: Map<String, bool>.from(json['features'] as Map),
    );
  }
}

class TenantRepository {
  final Dio _dio;
  final Box _cache; // Hive, por exemplo

  TenantRepository(this._dio, this._cache);

  Future<TenantConfig> resolve(String tenantId) async {
    try {
      final response = await _dio
          .get('/tenants/$tenantId/config')
          .timeout(const Duration(seconds: 5));
      final config = TenantConfig.fromJson(response.data);
      await _cache.put('tenant_config_$tenantId', response.data);
      return config;
    } catch (_) {
      // Sem rede ou timeout: cai para o último config salvo.
      final cached = _cache.get('tenant_config_$tenantId');
      if (cached != null) {
        return TenantConfig.fromJson(Map<String, dynamic>.from(cached));
      }
      // Sem cache e sem rede: fallback para um tema neutro,
      // nunca para o tema de outro tenant.
      return TenantConfig.fallback();
    }
  }
}

// Bootstrap
Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  final tenantId = await TenantResolver.detect(); // domínio, deep link, etc.
  final config = await TenantRepository(dio, cacheBox).resolve(tenantId);
  runApp(MyApp(theme: buildTheme(config), features: config.features));
}

Feature flags junto do tema

Já que a config vem de um endpoint, é natural embutir feature flags no mesmo payload:

{
  "tenantId": "tenant_a",
  "primaryColor": "0xFF2DD4BF",
  "logoUrl": "https://cdn.exemplo.com/tenant_a/logo.png",
  "features": {
    "pixEnabled": true,
    "cardVirtualEnabled": false,
    "biometricLogin": true
  }
}

if (tenantConfig.features['pixEnabled'] == true) {
  return const PixButton();
}

Trade-offs

A favor:

Um único build, uma única submissão de loja (quando o nome do app e o ícone não variam por marca).
Mudar cor, texto ou ligar/desligar uma feature não exige rebuild nem nova aprovação de loja — é uma alteração no backend.
Escala bem para dezenas de tenants sem custo de CI/CD adicional por tenant.

Contra:

Depende de rede na primeira execução (ou de um cache/fallback bem pensado para funcionar offline depois).
applicationId, nome do app e ícone na loja continuam sendo os mesmos para todo mundo — se cada marca precisa de um app com nome próprio na loja, essa técnica sozinha não resolve.
Superfície de erro nova: um bug no backend de config pode quebrar o tema de todos os tenants ao mesmo tempo, ou pior, vazar a configuração de um tenant para outro se o endpoint não isolar bem por tenant_id.
Exige uma peça de infraestrutura (o serviço de config) que as duas técnicas anteriores não exigem.

Use quando: o número de tenants é alto, a marca muda com frequência (rebranding, campanhas sazonais, testes A/B de tema), e o applicationId/nome na loja pode ser compartilhado entre tenants (por exemplo, um único app "guarda-chuva" com seleção de empresa no login).

Combinando as três (o caminho mais comum na prática)

Projetos com white label maduro raramente escolhem só uma técnica. Um padrão comum:

Flavors resolvem o que é impossível de mudar em runtime: applicationId, nome do app na loja, ícone, permissões nativas — geralmente para um número pequeno de tenants "grandes" que exigem app próprio na loja.
Dentro de cada flavor, configuração por endpoint resolve tema, textos e feature flags — porque mesmo o tenant que tem app próprio na loja quer poder trocar a cor do botão sem esperar aprovação da Apple.
Pasta por tenant + script aparece como uma alternativa mais leve a flavors quando o requisito de applicationId próprio não existe, mas ainda se quer builds separados (por exemplo, para times menores que não querem manter uma infra de config remota).

Ou seja: build-time para o que é estrutural e raramente muda, runtime para o que é visual/comportamental e muda o tempo todo.

Guia de decisão rápido

Cada marca precisa aparecer com nome e ícone próprios na loja? → precisa de flavors (ou pasta + script), não tem como fugir disso só com endpoint.
Menos de ~10 tenants, sem infraestrutura de backend dedicada, diferenças são só visuais? → pasta por tenant + script.
Mais de ~15-20 tenants, marca muda com frequência, mesmo applicationId para todos é aceitável? → configuração por endpoint.
Tudo isso ao mesmo tempo? → flavors (ou pasta) para o estrutural, endpoint para o resto. É mais trabalho de arquitetura, mas é o que escala.

Fechando

Nenhuma das três técnicas é "melhor" isoladamente — cada uma resolve um tipo de variação diferente entre tenants. O erro mais comum é tentar forçar o endpoint de config a fazer o trabalho dos flavors (mudar applicationId em runtime é impossível) ou o contrário, usar flavors para algo que muda toda semana e devia estar num backend.

Se você já implementou white label em Flutter, queria saber: qual dessas técnicas você usou, e o que te fez trocar de uma para outra?

Trabalho como Flutter Sênior remoto, com Go como segunda stack. Se quiser trocar ideia sobre isso ou sobre outras arquiteturas de white label, me encontra no GitHub ou no LinkedIn.

Flutter - Builder Pattern - Gerando textos estilizados

Wesley Oliveira — Thu, 11 Feb 2021 15:10:52 +0000

Recentemente comecei a estudar um pouco de Swift/IOS para poder "sair do 0", saber como funciona as coisas nesse mundo até então desconhecido para mim.

Resolvi fazer um curso básico no site, Raywenderlich , que por sinal um excelente curso.

Logo no começo do curso achei diferente a forma como são gerados os componentes visuais, diferente das widgets do flutter lá tudo são views.

A forma como são geradas essas views lembram bastante o design pattern builder ¹, como pode ser visto abaixo.

¹ Caso não tenha conhecimento sobre esse padrão sugiro assistir esse vídeo Builder Pattern.

Transformando a view acima para flutter teriamos algo semelhante a isto:

Como pode ser visto tem uma grande diferença na forma como são criados.

A partir desse ponto, irei focar apenas no flutter.

O Problema

Imagine uma situação onde em uma mesma linha deva ter diversos estilos textuais aplicados, por exemplo.

Texto em negrito, texto em italico, texto normal.

Flutter tem o poder de transformar isso em tarefa bem simples, aplicando apenas uma Text com alguns TextSpan isso se torna uma tarefa fácil como está na imagem abaixo.

E se forem mais estilos, 10, 20, claro que isso é um cenário difícil de acontecer, mas caso aconteça, o quanto esse widget iria crescer?

Solução proposta

Pensando nesse improvável panorama, lembrei da implementação do IOS e com o pattern Builder, pensei em tentar adaptar para o flutter.

Depois de algum tempo estudando, cheguei a esse pequeno esboço.

Flutter Gerador Textos Estilizados

A implementação foi feita seguindo o Builder pattern, e para utiliza-lo ficou bastante simples.

Como tudo no mundo da programação, não existe uma bala de prata! Existem N cenários e cada um deve ser avaliado a melhor opção, além de que isso é apenas uma ideia de algo pode ou não ser útil para alguém, mas afim de compartilhar um aprendizado resolvi escrever esse post.

Flutter Image File Upload - Base64 x MultiPart Form

Wesley Oliveira — Mon, 11 Jan 2021 14:34:34 +0000

Recentemente comecei a pesquisar diferentes temas que poderiam ser utilizados para escrever algum conteúdo, foi aí que um amigo escreveu o primeiro artigo e utilizou de um problema que aconteceu em seu dia a dia para transformá-lo em uma ideia de artigo, para escrever esse pequeno artigo resolvi tentar da mesma maneira.

Passamos por uns erros no quesito de upload de uma imagem para a api via Base64, resolvi então mostrar aqui alguns problemas dessa abordagem e uma alternativa para a mesma.

Base64 é um método para codificação de dados para transferência na Internet. É utilizado frequentemente para transmitir dados binários por meios de transmissão que lidam apenas com texto, como por exemplo para enviar arquivos anexos por e-mail.

Para converter um arquivo para Base64 no flutter é muito simples vide código baixo:

File file = await ImagePicker.pickImage(source: ImageSource.camera);
String base64 = base64Encode(file.readAsBytesSync());

¹ ImagePicker - Plugin Flutter para iOS e Android para selecionar imagens da galeria ou tirar uma nova foto com a câmera. Link

Obtido o Base64, o mesmo pode ser enviado no body de uma requisição post por exemplo.

Problemas com Base64

Respostas de API ficam muito grandes

Respostas muito grandes tendem a levar mais tempo para serem processadas dando mais tempo para uma possível falha na rede e aumentando o consumo de dados do dispositivo.

Oversizing

O tamanho da imagem codificada em Base64 é aproximadamente 30% maior do que a imagem binária original.

A experiência do usuário é afetada negativamente.

Incluindo os retornos junto com outras respostas da API, o aplicativo irá esperar carregar todos os dados antes de exibir informações na tela, afetando assim a experiência do usuário que verá uma tela de carregamento por mais tempo.

O armazenamento em cache de imagens no dispositivo não é mais possível.

Imagens enviadas para o dispositivo via Base64 tornará irrelevante qualquer implementação de serviços de cache de armazenamento de imagens.

Recursos nativos do flutter como o precacheImage tornam-se inutilizáveis nesta situação, já que toda vez será necessário fazer o decode do base64.

Outra implementação que se torna inutilizável seria o cachedNetworkImage, outra implementação nativa do flutter, mas que não pode ser aplicada ao contexto de um Base64.

Para aplicativos que possam funcionar tanto online quanto offline, a utilização de cache de imagens é um recurso bem eficaz para melhor experiência do usuário.

Vantagens do Base64

Remover a necessidade de múltiplos request, para obtenção de dados. ²
Imagens codificadas como Base64 podem ser armazenadas em bancos de dados e gerados novos arquivos. ² Como foi mostrado antes, essa abordagem pode ser uma vantagem ou uma desvantagem a depender do contexto e da implementação

Multipart Form Data

É uma de três formas de codificação existentes no HTML sendo elas:

1.application/x-www-form-urlencoded
2.multipart/form-data
3.text/plain

Deve-se utilizar esta forma de codificação quando a requisição possuir algum arquivo que deve fazer upload
É compatível com todos os navegadores.
Suporta arquivos com tamanhos muito grandes.

Utilizando multipart com Flutter

File file = await ImagePicker.pickImage(source: ImageSource.camera);
final multiPartdata = await MultipartFile.fromFile(file.path);
final formData = FormData.fromMap({
     "file": multiPartdata,
});

Desta maneira o servidor da API deve estar preparado para receber requisições com o cabeçalho multipart/form-data, já que o conteúdo não irá junto com o body da requisição caso o mesmo exista.

Alguns servidores de storage como aws.s3, cloudinary, firebase cloud storage, estão preparados para receberem requisições nesse formato, possuindo libs para integração direta em Flutter, dispensando a necessidade da criação de uma api própria.

Resolvendo o Oversizing

Algumas estratégias podem ser admitidas a fim de reduzir o oversizing, a mais comum são os famosos thumbnails, algumas alternativas mais recentes que têm grande aplicabilidade a depender do contexto seriam o blurHash e a Dominant color abaixo explico o funcionamento de ambas.

Thumbnails

Uma thumbnail é uma imagem comprimida que prevê a imagem original. Elas são mais leves e podem ser utilizadas para diversos fins. Por exemplo, um dos propósitos da utilização dessa thumb é reduzir o tempo de carregamento de alguma pagina na internet, para tornar o acesso mais rápido ao usuário. Então, uma thumbnail de uma foto maior, seria uma versão reduzida dela mesma.

Em essência, a principal função de uma miniatura é trazer uma informação ao usuário de maneira mais rápida.

Blurhash

“BlurHash is a compact representation of a placeholder for an image”.

Blurhash é uma representação compacta de um espaço reservado para uma imagem. Esta é a definição dada pelos desenvolvedores. Trata-se de uma biblioteca que converte uma imagem para uma versão ofuscada e compactada de sua versão.
Essa biblioteca possui implementações para diversas linguagens, typescript, kotlin, swift, python, C, entre outras. Segue abaixo uma visão da mesma.

Dominant color

Trata-se apenas de pegar a cor de maior incidência na imagem, e utilizá-la no local da mesma. Estratégia bastante parecida com o blurHash, a diferença seria apenas o resultado final da imagem.