Introdução à Configuração remota do Firebase

iOS+ Android Web Flutter Unity C++

Importante: nesta seção, descrevemos as etapas para configurar Remote Config com clientes da Web e de dispositivos móveis. Para ambientes de servidor, consulte Usar Remote Config em ambientes de servidor.

Use Firebase Remote Config para definir parâmetros no app e atualizar os respectivos valores na nuvem. Assim, você modifica a aparência e o comportamento do app sem precisar distribuir uma atualização. Este guia traz as noções básicas e os exemplos de código, que estão disponíveis para clonagem ou download no repositório do GitHub firebase/quickstart-ios.

Etapa 1: adicionar Remote Config ao app

1. Adicione o Firebase ao seu projeto da Apple caso ainda não tenha feito isso.

2. Em Remote Config, Google Analytics é necessário para a segmentação condicional de instâncias de app para propriedades de usuário e públicos. Ative Google Analytics no projeto.

3. Crie o objeto singleton de Remote Config, conforme mostrado neste exemplo:

   Swift

   remoteConfig = RemoteConfig.remoteConfig()
   let settings = RemoteConfigSettings()
   settings.minimumFetchInterval = 0
   remoteConfig.configSettings = settings
   ViewController.swift

   Objective-C

   self.remoteConfig = [FIRRemoteConfig remoteConfig];
   FIRRemoteConfigSettings *remoteConfigSettings = [[FIRRemoteConfigSettings alloc] init];
   remoteConfigSettings.minimumFetchInterval = 0;
   self.remoteConfig.configSettings = remoteConfigSettings;
   ViewController.m

Esse objeto é usado para armazenar valores de parâmetro padrão no app, buscar valores de parâmetro atualizados no back-end de Remote Config e controlar quando eles são disponibilizados ao app.

Durante o desenvolvimento, recomendamos definir um intervalo de busca mínimo relativamente baixo. Para mais informações, consulte Limitação.

Etapa 2: definir valores de parâmetros padrão no app

É possível definir os valores de parâmetro padrão no app com Remote Config. Assim, o app se comporta de maneira previsível antes de se conectar ao back-end de Remote Config e os valores padrão ficam disponíveis, caso nenhum tenha sido definido no back-end.

Importante: não armazene dados confidenciais em chaves ou valores de parâmetros de Remote Config. Os dados de Remote Config são criptografados em trânsito, mas os usuários finais podem acessar qualquer parâmetro padrão ou buscado de Remote Config que esteja disponível para a instância do app cliente.

1. Defina um conjunto de nomes e valores de parâmetros padrão usando um objeto NSDictionary ou um arquivo plist (links em inglês).

   Depois de configurar os valores de parâmetro do back-end de Remote Config, é possível fazer o download de um arquivo plist gerado com todos os valores padrão e salvar esse arquivo no projeto do Xcode.

   REST

   curl --compressed -D headers -H "Authorization: Bearer token -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=PLIST -o RemoteConfigDefaults.plist
   

   Console do Firebase

   1. Na guia Parâmetros, abra o Menu e selecione Fazer o download dos valores padrão.

   2. Quando solicitado, ative a opção .plist para iOS, e clique em Fazer o download do arquivo.

2. Adicione esses valores ao objeto de Remote Config usando setDefaults:. O exemplo a seguir define valores padrão no aplicativo de um arquivo plist:

   Swift

   remoteConfig.setDefaults(fromPlist: "RemoteConfigDefaults")
   ViewController.swift

   Objective-C

   [self.remoteConfig setDefaultsFromPlistFileName:@"RemoteConfigDefaults"];
   ViewController.m

Observação: esses snippets de código são referentes ao arquivo RemoteConfigDefaults.plist do projeto quickstart-ios de exemplo. Se você usar o arquivo padrão salvo, é possível utilizar remote_config_defaults.

Etapa 3: receber valores de parâmetros para uso no app

Agora você pode receber valores de parâmetro do objeto de Remote Config. Se você definir valores no back-end de Remote Config, buscá-los e ativá-los, eles vão estar disponíveis para o app. Caso contrário, você vai receber os valores de parâmetro configurados no app com setDefaults:. Para receber esses valores, chame o método configValueForKey: fornecendo a chave de parâmetro como argumento.

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a parameter value using configValueForKey
let welcomeMessageValue = remoteConfig.configValue(forKey: "welcome_message")
let welcomeMessage = welcomeMessageValue.stringValue

let featureFlagValue = remoteConfig.configValue(forKey: "new_feature_flag")
let isFeatureEnabled = featureFlagValue.boolValue

Uma maneira mais legível e conveniente de acessar esses valores no Swift é usando a notação de índice:

let remoteConfig = RemoteConfig.remoteConfig()

// Retrieve a string parameter value
let welcomeMessage = remoteConfig["welcome_message"].stringValue

// Retrieve a boolean parameter value
let isFeatureEnabled = remoteConfig["new_feature_flag"].boolValue

// Retrieve a number parameter value
let maxItemCount = remoteConfig["max_items"].numberValue.intValue

Usar o Codable para configuração segura de tipos

Para configurações mais complexas, use o protocolo Codable do Swift para decodificar dados estruturados de Remote Config. Isso oferece gerenciamento de configuração seguro para tipos e simplifica o trabalho com objetos complexos.

// Define a Codable struct for your configuration
struct AppFeatureConfig: Codable {
  let isNewFeatureEnabled: Bool
  let maxUploadSize: Int
  let themeColors: [String: String]
}

// Fetch and decode the configuration
func configureAppFeatures() {
  let remoteConfig = RemoteConfig.remoteConfig()
  remoteConfig.fetchAndActivate { status, error in
    guard error == nil else { return }

    do {
      let featureConfig = try remoteConfig["app_feature_config"].decoded(asType: AppFeatureConfig.self)
      configureApp(with: featureConfig)
    } catch {
      // Handle decoding errors
      print("Failed to decode configuration: \(error)")
    }
  }
}

Esse método permite:

• Definir estruturas de configuração complexas.
• Analisar automaticamente as configurações JSON.
• Garanta a segurança de tipos ao acessar valores Remote Config.
• Forneça um código limpo e legível para processar modelos Remote Config estruturados.

Usar wrappers de propriedade para configuração declarativa no SwiftUI

Os wrappers de propriedade são um recurso Swift poderoso que permite adicionar comportamento personalizado às declarações de propriedade. No SwiftUI, os wrappers de propriedade são usados para gerenciar estado, vinculações e outros comportamentos de propriedade. Para mais informações, consulte o Guia de linguagem Swift.

struct ContentView: View {
  @RemoteConfigProperty(key: "cardColor", fallback: "#f05138")
  var cardColor

  var body: some View {
    VStack {
      Text("Dynamic Configuration")
        .background(Color(hex: cardColor))
    }
    .onAppear {
      RemoteConfig.remoteConfig().fetchAndActivate()
    }
  }
}

Use o wrapper de propriedade @RemoteConfigProperty quando quiser uma maneira declarativa de acessar valores Remote Config no SwiftUI, com suporte integrado para valores padrão e gerenciamento de configuração simplificado.

Etapa 4: definir valores de parâmetros

Com o console de Firebase ou as APIs de back-end de Remote Config, é possível criar valores padrão do back-end que substituem os valores no app de acordo com a lógica condicional ou a segmentação de usuário pretendidas. Nesta seção, confira as etapas a serem seguidas no console de Firebase para criar esses valores.

1. Abra o projeto no console de Firebase.
2. Selecione Remote Config no menu para acessar o painel de Remote Config.
3. Defina os parâmetros com os mesmos nomes dos definidos no seu app. Para cada um, é possível definir um valor padrão (que possivelmente substituirá o valor padrão no app) e também valores condicionais. Saiba mais em Parâmetros e condições de Remote Config.

4. Ao usar condições de indicador personalizado, defina os atributos e os valores deles. Os exemplos a seguir mostram como definir uma condição de indicador personalizado.

   Swift

     Task {
         let customSignals: [String: CustomSignalValue?] = [
         "city": .string("Tokyo"),
         "preferred_event_category": .string("sports")
       ]
   
       do {
         try await remoteConfig.setCustomSignals(customSignals)
         print("Custom signals set successfully!")
         } catch {
             print("Error setting custom signals: \(error)")
         }
   }

   Objective-C

     dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
       NSDictionary *customSignals = @{
         @"city": @"Tokyo",
         @"preferred_event_category": @"sports"
       };
   
       [self.remoteConfig setCustomSignals:customSignals withCompletion:^(NSError * _Nullable error) {
           if (error) {
               NSLog(@"Error setting custom signals: %@", error);
           } else {
               NSLog(@"Custom signals set successfully!");
           }
     }];
   });

Etapa 5: buscar e ativar valores

Para buscar os valores de parâmetro de Remote Config, chame o método fetchWithCompletionHandler: ou fetchWithExpirationDuration:completionHandler:. Todos os valores definidos no back-end são buscados e armazenados em cache no objeto de Remote Config.

Para buscar e ativar valores com uma chamada, use fetchAndActivateWithCompletionHandler:.

Este exemplo busca valores no back-end de Remote Config (não valores em cache) e chama activateWithCompletionHandler: para disponibilizá-los ao app:

Swift

remoteConfig.fetch { (status, error) -> Void in
  if status == .success {
    print("Config fetched!")
    self.remoteConfig.activate { changed, error in
      // ...
    }
  } else {
    print("Config not fetched")
    print("Error: \(error?.localizedDescription ?? "No error available.")")
  }
  self.displayWelcome()
}
ViewController.swift

Objective-C

[self.remoteConfig fetchWithCompletionHandler:^(FIRRemoteConfigFetchStatus status, NSError *error) {
    if (status == FIRRemoteConfigFetchStatusSuccess) {
        NSLog(@"Config fetched!");
      [self.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
        if (error != nil) {
          NSLog(@"Activate error: %@", error.localizedDescription);
        } else {
          dispatch_async(dispatch_get_main_queue(), ^{
            [self displayWelcome];
          });
        }
      }];
    } else {
        NSLog(@"Config not fetched");
        NSLog(@"Error %@", error.localizedDescription);
    }
}];
ViewController.m

Esses valores de parâmetro atualizados afetam o comportamento e a aparência do app. Por isso, ative-os sem prejudicar a experiência do usuário, como da próxima vez que ele abrir o app. Confira informações e exemplos em Estratégias de carregamento da Configuração remota.

Etapa 6: detectar atualizações em tempo real

Depois de buscar valores de parâmetros, é possível usar Remote Config em tempo real para detectar atualizações do back-end de Remote Config. Remote Config em tempo real sinaliza para dispositivos conectados quando atualizações estão disponíveis e busca as mudanças automaticamente depois que você publica uma nova versão de Remote Config.

O SDK de Firebase para plataformas Apple v10.7.0 e mais recente é compatível com atualizações em tempo real.

Importante: Remote Config em tempo real também exige a API Realtime de Firebase Remote Config, que já deve estar ativada. Para verificar, abra o console de Google Cloud, selecione o projeto e abra a página APIs e serviços. A API precisa aparecer como ativada. Se ela estiver ausente ou desativada, clique em Ativar APIs e serviços, encontre a API Realtime de Firebase Remote Config e ative-a.

1. No seu app, chame addOnConfigUpdateListener para detectar atualizações e buscar novos valores de parâmetros automaticamente. O exemplo a seguir detecta atualizações e usa os valores recém-buscados quando activateWithCompletionHandler é chamado para mostrar uma mensagem de boas-vindas atualizada.

   Swift

   remoteConfig.addOnConfigUpdateListener { configUpdate, error in
     guard let configUpdate, error == nil else {
       print("Error listening for config updates: \(error)")
     }
   
     print("Updated keys: \(configUpdate.updatedKeys)")
   
     self.remoteConfig.activate { changed, error in
       guard error == nil else { return self.displayError(error) }
       DispatchQueue.main.async {
         self.displayWelcome()
       }
     }
   }

   Objective-C

   __weak __typeof__(self) weakSelf = self;
   [self.remoteConfig addOnConfigUpdateListener:^(FIRRemoteConfigUpdate * _Nonnull configUpdate, NSError * _Nullable error) {
     if (error != nil) {
       NSLog(@"Error listening for config updates %@", error.localizedDescription);
     } else {
       NSLog(@"Updated keys: %@", configUpdate.updatedKeys);
   
       __typeof__(self) strongSelf = weakSelf;
       [strongSelf.remoteConfig activateWithCompletion:^(BOOL changed, NSError * _Nullable error) {
         if (error != nil) {
           NSLog(@"Activate error %@", error.localizedDescription);
         }
   
         dispatch_async(dispatch_get_main_queue(), ^{
           [strongSelf displayWelcome];
         });
       }];
     }
   }];

2. Na próxima vez que você publicar uma nova versão de Remote Config, os dispositivos que estão executando o app e detectando as mudanças vão chamar o gerenciador de conclusão.

Limitação

Se um aplicativo fizer muitas buscas em um curto período, as chamadas de busca serão limitadas, e o SDK retornará FIRRemoteConfigFetchStatusThrottled. Antes da versão 6.3.0 do SDK, o limite era de cinco solicitações de busca em um intervalo de 60 minutos. As versões mais recentes têm limites mais flexíveis.

Dica: com o SDK para plataformas Apple v10.7.0 ou mais recente, é possível usar Remote Config em tempo real para buscar automaticamente valores de parâmetro atualizados no back-end de Remote Config assim que eles são publicados, ignorando qualquer configuração mínima do intervalo de busca. É possível usar as atualizações em tempo real em vez de fazer buscas com frequência para atualizar o cache. Para mais informações, consulte Detectar atualizações em tempo real.

Durante o desenvolvimento de apps, sempre faça buscas para atualizar o cache com mais frequência (muitas vezes por hora) para permitir a iteração rápida enquanto você desenvolve e testa seu app. As atualizações da Configuração remota em tempo real ignoram automaticamente o cache quando a configuração é atualizada no servidor. Caso queira acomodar a iteração rápida em um projeto com vários desenvolvedores, é possível adicionar temporariamente uma propriedade FIRRemoteConfigSettings com um intervalo de busca mínimo baixo (MinimumFetchInterval) no app.

O intervalo de busca de produção padrão e recomendado para Remote Config é de 12 horas, o que significa que a busca pelas configurações no back-end não acontecerá mais de uma vez em um período de 12 horas, independentemente de quantas chamadas de busca forem realmente realizadas. O intervalo mínimo de busca é determinado especificamente na seguinte ordem:

1. O parâmetro em fetch(long)
2. O parâmetro em FIRRemoteConfigSettings.MinimumFetchInterval
3. O valor padrão de 12 horas

Essa configuração deve ser usada apenas para desenvolvimento e não para um app em execução na produção. Se você está apenas testando seu aplicativo com uma equipe de desenvolvimento pequena de 10 pessoas, é improvável que atinja os limites de cota do serviço por hora. No entanto, se você transferiu seu aplicativo para milhares de usuários de teste com um intervalo de busca mínimo muito baixo, seu app provavelmente atingirá essa cota.

Próximas etapas

Se ainda não tiver feito isso, confira os casos de uso de Remote Config, bem como alguns dos principais conceitos e a documentação de estratégias avançadas, que incluem:

• Gerenciar versões de modelo de Remote Config
• Estratégias de carregamento de configuração