Modifica la configurazione remota a livello di codice

Questo documento descrive come leggere e modificare in modo programmatico il set di parametri e condizioni in formato JSON noto come modello Remote Config . Ciò consente di apportare modifiche al modello nel back-end che l'app client può recuperare utilizzando la libreria client.

Utilizzando l' API REST di Remote Config o gli SDK Admin descritti in questa guida, puoi ignorare la gestione del modello nella console Firebase per integrare direttamente le modifiche di Remote Config nei tuoi processi. Ad esempio, con le API di backend Remote Config, puoi:

• Pianificazione degli aggiornamenti di Remote Config . Utilizzando le chiamate API insieme a un cron job, puoi modificare i valori di Remote Config con una pianificazione regolare.
• Importa in batch i valori di configurazione per passare in modo efficiente dal tuo sistema proprietario a Firebase Remote Config.

• Usa Remote Config with Cloud Functions for Firebase , modificando i valori nella tua app in base agli eventi che si verificano sul lato server. Ad esempio, puoi utilizzare Remote Config per promuovere una nuova funzionalità nella tua app e quindi disattivare tale promozione automaticamente quando rilevi che un numero sufficiente di persone ha interagito con la nuova funzionalità.

  

Le seguenti sezioni di questa guida descrivono le operazioni che puoi eseguire con le API di back-end di Remote Config. Per esaminare parte del codice che esegue queste attività tramite l'API REST, vedere una di queste app di esempio:

• Avvio rapido Java dell'API REST di Firebase Remote Config
• Firebase Remote Config REST API Node.js Avvio rapido
• Firebase Remote Config REST API Python Quickstart

Modifica Remote Config utilizzando Firebase Admin SDK

Admin SDK è un insieme di librerie server che ti consentono di interagire con Firebase da ambienti privilegiati. Oltre a eseguire aggiornamenti a Remote Config, Admin SDK consente la generazione e la verifica dei token di autenticazione Firebase, la lettura e la scrittura da Realtime Database e così via. Per ulteriori informazioni sui prerequisiti e sulla configurazione dell'SDK Admin, consulta Aggiungere l'SDK Admin Firebase al server .

In un tipico flusso Remote Config, potresti ottenere il modello corrente, modificare alcuni parametri o gruppi di parametri e condizioni, convalidare il modello e quindi pubblicarlo. Prima di effettuare tali chiamate API, devi autorizzare le richieste dall'SDK.

Inizializza l'SDK e autorizza le richieste API

Quando si inizializza l'Admin SDK senza parametri, l'SDK utilizza le credenziali predefinite dell'applicazione Google e legge le opzioni dalla variabile di ambiente FIREBASE_CONFIG . Se il contenuto della variabile FIREBASE_CONFIG inizia con un { verrà analizzato come oggetto JSON. In caso contrario, l'SDK presuppone che la stringa sia il nome di un file JSON contenente le opzioni.

Per esempio:

const admin = require('firebase-admin');
admin.initializeApp();

FileInputStream serviceAccount = new FileInputStream("service-account.json");
FirebaseOptions options = FirebaseOptions.builder()
        .setCredentials(GoogleCredentials.fromStream(serviceAccount))
        .build();
FirebaseApp.initializeApp(options);

Ottieni il modello di configurazione remota corrente

Quando lavori con i modelli Remote Config, tieni presente che sono dotati di versione e che ogni versione ha una durata limitata dal momento della creazione al momento in cui la sostituisci con un aggiornamento: 90 giorni, con un limite totale di 300 versioni archiviate. Vedere Modelli e controllo delle versioni per ulteriori informazioni.

Puoi utilizzare le API di back-end per ottenere la versione attiva corrente del modello Remote Config in formato JSON.

I parametri e i valori dei parametri creati appositamente come varianti in un esperimento di test A/B non sono inclusi nei modelli esportati.

Per ottenere il modello:

function getTemplate() {
  var config = admin.remoteConfig();
  config.getTemplate()
      .then(function (template) {
        console.log('ETag from server: ' + template.etag);
        var templateStr = JSON.stringify(template);
        fs.writeFileSync('config.json', templateStr);
      })
      .catch(function (err) {
        console.error('Unable to get template');
        console.error(err);
      });
}

Template template = FirebaseRemoteConfig.getInstance().getTemplateAsync().get();
// See the ETag of the fetched template.
System.out.println("ETag from server: " + template.getETag());

Modifica i parametri di Remote Config

È possibile modificare e aggiungere a livello di programmazione parametri e gruppi di parametri di Remote Config. Ad esempio, a un gruppo di parametri esistente denominato "nuovo_menu" è possibile aggiungere un parametro per controllare la visualizzazione delle informazioni stagionali:

function addParameterToGroup(template) {
  template.parameterGroups['new_menu'].parameters['spring_season'] = {
    defaultValue: {
      useInAppDefault: true
    },
    description: 'spring season menu visibility.',
  };
}

template.getParameterGroups().get("new_menu").getParameters()
        .put("spring_season", new Parameter()
                .setDefaultValue(ParameterValue.inAppDefault())
                .setDescription("spring season menu visibility.")
        );

L'API consente di creare nuovi parametri e gruppi di parametri o modificare i valori predefiniti, i valori condizionali e le descrizioni. In tutti i casi, è necessario pubblicare esplicitamente il modello dopo aver apportato le modifiche.

Modificare le condizioni di Remote Config

È possibile modificare e aggiungere a livello di codice condizioni e valori condizionali di Remote Config. Ad esempio, per aggiungere una nuova condizione:

function addNewCondition(template) {
  template.conditions.push({
    name: 'android_en',
    expression: 'device.os == \'android\' && device.country in [\'us\', \'uk\']',
    tagColor: 'BLUE',
  });
}

template.getConditions().add(new Condition("android_en",
        "device.os == 'android' && device.country in ['us', 'uk']", TagColor.BLUE));

In tutti i casi, è necessario pubblicare esplicitamente il modello dopo aver apportato le modifiche.

Le API back-end di Remote Config forniscono diverse condizioni e operatori di confronto che puoi utilizzare per modificare il comportamento e l'aspetto della tua app. Per ulteriori informazioni sulle condizioni e sugli operatori supportati per queste condizioni, vedere il riferimento all'espressione condizionale .

Convalida il modello Remote Config

Facoltativamente, puoi convalidare i tuoi aggiornamenti prima di pubblicarli, come mostrato:

function validateTemplate(template) {
  admin.remoteConfig().validateTemplate(template)
      .then(function (validatedTemplate) {
        // The template is valid and safe to use.
        console.log('Template was valid and safe to use');
      })
      .catch(function (err) {
        console.error('Template is invalid and cannot be published');
        console.error(err);
      });
}

try {
  Template validatedTemplate = FirebaseRemoteConfig.getInstance()
          .validateTemplateAsync(template).get();
  System.out.println("Template was valid and safe to use");
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Template is invalid and cannot be published");
    System.out.println(rcError.getMessage());
  }
}

Questo processo di convalida verifica la presenza di errori come chiavi duplicate per parametri e condizioni, nomi di condizioni non validi o condizioni inesistenti o etag formattati in modo errato. Ad esempio, una richiesta contenente un numero di chiavi superiore a quello consentito, 2000, restituirà il messaggio di errore Param count too large .

Pubblica il modello Remote Config

Dopo aver recuperato un modello e averlo revisionato con gli aggiornamenti desiderati, è possibile pubblicarlo. La pubblicazione di un modello come descritto in questa sezione sostituisce l'intero modello di configurazione esistente con il file aggiornato e al nuovo modello attivo viene assegnato un numero di versione maggiore di un numero rispetto al modello che ha sostituito.

Se necessario, puoi utilizzare l'API REST per eseguire il rollback alla versione precedente . Per mitigare il rischio di errori in un aggiornamento, puoi convalidare prima della pubblicazione .

Le personalizzazioni e le condizioni di Remote Config sono incluse nei modelli scaricati, quindi è importante essere consapevoli delle seguenti limitazioni quando si tenta di pubblicare in un progetto diverso:

• Le personalizzazioni non possono essere importate da progetto a progetto.

  Ad esempio, se hai abilitato le personalizzazioni nel tuo progetto e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non puoi pubblicarlo in un altro progetto a meno che non elimini le personalizzazioni dal modello.

• Le condizioni possono essere importate da progetto a progetto, ma tieni presente che eventuali valori condizionali specifici (come ID app o segmenti di pubblico) devono esistere nel progetto di destinazione prima della pubblicazione.

  Ad esempio, se disponi di un parametro Remote Config che utilizza una condizione che specifica un valore di piattaforma iOS , il modello può essere pubblicato in un altro progetto, poiché i valori di piattaforma sono gli stessi per qualsiasi progetto. Tuttavia, se contiene una condizione che si basa su un ID app specifico o su un pubblico di utenti che non esiste nel progetto di destinazione, la convalida avrà esito negativo.

• Se il modello che intendi pubblicare contiene condizioni che si basano su Google Analytics, Analytics deve essere abilitato nel progetto di destinazione.

function publishTemplate() {
  var config = admin.remoteConfig();
  var template = config.createTemplateFromJSON(
      fs.readFileSync('config.json', 'UTF8'));
  config.publishTemplate(template)
      .then(function (updatedTemplate) {
        console.log('Template has been published');
        console.log('ETag from server: ' + updatedTemplate.etag);
      })
      .catch(function (err) {
        console.error('Unable to publish template.');
        console.error(err);
      });
}

try {
  Template publishedTemplate = FirebaseRemoteConfig.getInstance()
          .publishTemplateAsync(template).get();
  System.out.println("Template has been published");
  // See the ETag of the published template.
  System.out.println("ETag from server: " + publishedTemplate.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Unable to publish template.");
    System.out.println(rcError.getMessage());
  }
}

Modifica la configurazione remota utilizzando l'API REST

Questa sezione descrive le funzionalità principali dell'API REST Remote Config all'indirizzo https://firebaseremoteconfig.googleapis.com . Per i dettagli completi, vedere il riferimento API .

Ottieni un token di accesso per autenticare e autorizzare le richieste API

I progetti Firebase supportano gli account di servizio Google , che puoi utilizzare per chiamare le API del server Firebase dal tuo server dell'app o dall'ambiente attendibile. Se stai sviluppando codice in locale o distribuendo la tua applicazione in locale, puoi usare le credenziali ottenute tramite questo account di servizio per autorizzare le richieste del server.

Per autenticare un account di servizio e autorizzarlo ad accedere ai servizi Firebase, devi generare un file di chiave privata in formato JSON.

Per generare un file di chiave privata per il tuo account di servizio:

1. Nella console Firebase, apri Impostazioni > Account di servizio .

2. Fare clic su Genera nuova chiave privata , quindi confermare facendo clic su Genera chiave .

3. Archivia in modo sicuro il file JSON contenente la chiave.

Quando autorizzi tramite un account di servizio, hai due possibilità per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS oppure passare esplicitamente il percorso alla chiave dell'account di servizio nel codice. La prima opzione è più sicura ed è fortemente consigliata.

Per impostare la variabile di ambiente:

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON che contiene la chiave dell'account di servizio. Questa variabile si applica solo alla tua sessione di shell corrente, quindi se apri una nuova sessione, imposta nuovamente la variabile.

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Dopo aver completato i passaggi precedenti, ADC (Application Default Credentials) è in grado di determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali dell'account di servizio durante il test o l'esecuzione in ambienti non Google.

Usa le tue credenziali Firebase insieme a Google Auth Library per la tua lingua preferita per recuperare un token di accesso OAuth 2.0 di breve durata:

 function getAccessToken() {
  return admin.credential.applicationDefault().getAccessToken()
      .then(accessToken => {
        return accessToken.access_token;
      })
      .catch(err => {
        console.error('Unable to get access token');
        console.error(err);
      });
}
index.js

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token
configure.py

private static String getAccessToken() throws IOException {
  GoogleCredentials googleCredentials = GoogleCredentials
          .fromStream(new FileInputStream("service-account.json"))
          .createScoped(Arrays.asList(SCOPES));
  googleCredentials.refreshAccessToken();
  return googleCredentials.getAccessToken().getTokenValue();
}
Configure.java

Dopo la scadenza del token di accesso, il metodo di aggiornamento del token viene chiamato automaticamente per recuperare un token di accesso aggiornato.

Per autorizzare l'accesso a Remote Config, richiedi l'ambito https://www.googleapis.com/auth/firebase.remoteconfig .

Modificare il modello Remote Config

Quando lavori con i modelli Remote Config, tieni presente che sono dotati di versione e che ogni versione ha una durata limitata dal momento della creazione al momento in cui la sostituisci con un aggiornamento: 90 giorni, con un limite totale di 300 versioni archiviate. Vedere Modelli e controllo delle versioni per ulteriori informazioni.

Ottieni il modello di configurazione remota corrente

Puoi utilizzare le API di back-end per ottenere la versione attiva corrente del modello Remote Config in formato JSON.

I parametri e i valori dei parametri creati appositamente come varianti in un esperimento di test A/B non sono inclusi nei modelli esportati.

Usa i seguenti comandi:

curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -o filename

Host: firebaseremoteconfig.googleapis.com

GET /v1/projects/my-project-id/remoteConfig HTTP/1.1
Authorization: Bearer token
Accept-Encoding: gzip

Convalida il modello Remote Config

Facoltativamente, puoi convalidare i tuoi aggiornamenti prima di pubblicarli. Convalida gli aggiornamenti del modello aggiungendo alla tua richiesta di pubblicazione il parametro URL ?validate_only=true . Nella risposta, un codice di stato 200 e un etag aggiornato con il suffisso -0 indicano che l'aggiornamento è stato convalidato correttamente. Qualsiasi risposta diversa da 200 indica che i dati JSON contengono errori che devi correggere prima della pubblicazione.

Aggiorna il modello di configurazione remota

Dopo aver recuperato un modello e rivisto il contenuto JSON con gli aggiornamenti desiderati, puoi pubblicarlo. La pubblicazione di un modello come descritto in questa sezione sostituisce l'intero modello di configurazione esistente con il file aggiornato e al nuovo modello attivo viene assegnato un numero di versione maggiore di un numero rispetto al modello che ha sostituito.

Se necessario, puoi utilizzare l'API REST per eseguire il rollback alla versione precedente . Per mitigare il rischio di errori in un aggiornamento, puoi convalidare prima della pubblicazione .

Le personalizzazioni e le condizioni di Remote Config sono incluse nei modelli scaricati, quindi è importante essere consapevoli delle seguenti limitazioni quando si tenta di pubblicare in un progetto diverso:

• Le personalizzazioni non possono essere importate da progetto a progetto.

  Ad esempio, se hai abilitato le personalizzazioni nel tuo progetto e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non puoi pubblicarlo in un altro progetto a meno che non elimini le personalizzazioni dal modello.

• Le condizioni possono essere importate da progetto a progetto, ma tieni presente che eventuali valori condizionali specifici (come ID app o segmenti di pubblico) devono esistere nel progetto di destinazione prima della pubblicazione.

  Ad esempio, se disponi di un parametro Remote Config che utilizza una condizione che specifica un valore di piattaforma iOS , il modello può essere pubblicato in un altro progetto, poiché i valori di piattaforma sono gli stessi per qualsiasi progetto. Tuttavia, se contiene una condizione che si basa su un ID app specifico o su un pubblico di utenti che non esiste nel progetto di destinazione, la convalida avrà esito negativo.

• Se il modello che intendi pubblicare contiene condizioni che si basano su Google Analytics, Analytics deve essere abilitato nel progetto di destinazione.

curl --compressed -H "Content-Type: application/json; UTF8" -H "If-Match: last-returned-etag" -H "Authorization: Bearer token" -X PUT https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig -d @filename

Host: firebaseremoteconfig.googleapis.com
PUT /v1/projects/my-project-id/remoteConfig HTTP/1.1
Content-Length: size
Content-Type: application/json; UTF8
Authorization: Bearer token
If-Match: expected ETag
Accept-Encoding: gzip
JSON_HERE

Modificare le condizioni di Remote Config

È possibile modificare a livello di programmazione le condizioni e i valori condizionali di Remote Config. Con l'API REST, devi modificare direttamente il modello per modificare le condizioni prima di pubblicare il modello.

{
  "conditions": [{
    "name": "android_english",
    "expression": "device.os == 'android' && device.country in ['us', 'uk']",
    "tagColor": "BLUE"
  }, {
    "name": "tenPercent",
    "expression": "percent <= 10",
    "tagColor": "BROWN"
  }],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "tenPercent": {
          "value": "Welcome to this new sample app"
        }
      },
      "description": "The sample app's welcome message"
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      },
      "conditionalValues": {
        "android_english": {
          "value": "true"
        }
      },
      "description": "Whether the welcome message should be displayed in all capital letters."
    }
  }
}

Le modifiche precedenti definiscono innanzitutto un insieme di condizioni, quindi definiscono i valori predefiniti e i valori dei parametri basati sulle condizioni (valori condizionali ) per ciascun parametro. Aggiunge anche una descrizione facoltativa per ogni elemento; come i commenti sul codice, questi sono ad uso degli sviluppatori e non vengono visualizzati nell'app. Viene inoltre fornito un ETag per scopi di controllo della versione.

Le API back-end di Remote Config forniscono diverse condizioni e operatori di confronto che puoi utilizzare per modificare il comportamento e l'aspetto della tua app. Per ulteriori informazioni sulle condizioni e sugli operatori supportati per queste condizioni, vedere il riferimento all'espressione condizionale .

Codici di errore HTTP

Un codice di stato 200 indica che il modello Remote Config (parametri, valori e condizioni per il progetto) è stato aggiornato ed è ora disponibile per le app che usano questo progetto. Altri codici di stato indicano che il modello Remote Config che esisteva in precedenza è ancora attivo.

Dopo aver inviato gli aggiornamenti al modello, vai alla console di Firebase per verificare che le modifiche appaiano come previsto. Questo è fondamentale perché l'ordine delle condizioni influisce sul modo in cui vengono valutate (la prima condizione che valuta true ha effetto).

Utilizzo di ETag e aggiornamenti forzati

L'API REST Remote Config utilizza un tag di entità (ETag) per impedire condizioni di competizione e aggiornamenti sovrapposti alle risorse. Per ulteriori informazioni sugli ETag, vedere ETag - HTTP .

Per l'API REST, Google consiglia di memorizzare nella cache l'ETag fornito dal comando GET più recente e di utilizzare tale valore ETag nell'intestazione della richiesta If-Match durante l'emissione dei comandi PUT . Se il tuo comando PUT un codice di stato HTTPS 409, devi emettere un nuovo comando GET per acquisire un nuovo ETag e un modello da utilizzare con il tuo prossimo comando PUT .

È possibile aggirare l'ETag, e la protezione da esso fornita, forzando l'aggiornamento del modello Remote Config come segue: If-Match: * Tuttavia, questo approccio non è consigliato perché rischia di causare la perdita degli aggiornamenti della configurazione remota template se più client stanno aggiornando il modello Remote Config. Questo tipo di conflitto potrebbe verificarsi con più client che utilizzano l'API o con aggiornamenti in conflitto da client API e utenti della console Firebase.

Per indicazioni sulla gestione delle versioni dei modelli di Remote Config, consulta Modelli e controllo delle versioni di Remote Config .