Gestire i modelli client e il controllo delle versioni di Remote Config

Seleziona il tipo di modello: Modelli lato client Modelli lato server


I modelli Remote Config sono insiemi di parametri e condizioni in formato JSON creati per il tuo progetto Firebase. I modelli client forniscono configurazioni alle istanze dell'app che implementano gli SDK client Firebase per Remote Config, tra cui app Apple, Android, web, Flutter, Unity e C++.

Puoi utilizzare la console Firebase per modificare e gestire il modello client. Vai a DevOps e coinvolgimento > Remote Config per visualizzare i contenuti del modello in formato grafico nella pagina Parametri e nella pagina Condizioni.

Puoi anche utilizzare l'API REST Remote Config e Admin SDK o l'interfaccia a riga di comando Firebase per modificare e gestire il modello client.

Ecco un esempio di file di modello di client:

{
  "conditions": [
    {
      "name": "ios",
      "expression": "device.os == 'ios'"
    }
  ],
  "parameters": {
    "welcome_message": {
      "defaultValue": {
        "value": "Welcome to this sample app"
      },
      "conditionalValues": {
        "ios": {
          "value": "Welcome to this sample iOS app"
        }
      }
    },
    "welcome_message_caps": {
      "defaultValue": {
        "value": "false"
      }
    },
    "header_text": {
      "defaultValue": {
        "useInAppDefault": true
      }
    }
  },
  "version": {
    "versionNumber": "28",
    "updateTime": "2020-05-14T18:39:38.994Z",
    "updateUser": {
      "email": "user@google.com"
    },
    "updateOrigin": "CONSOLE",
    "updateType": "INCREMENTAL_UPDATE"
  }
}

Puoi eseguire queste attività di gestione delle versioni nella console Firebase (vai a DevOps e coinvolgimento > Remote Config):

  • Elenca tutte le versioni dei template archiviati
  • Recupera una versione specifica
  • Esegui il rollback a una versione client specifica
  • Elimina Remote Config modelli dalla pagina Cronologia delle modifiche.

Puoi anche elencare, recuperare ed eseguire il rollback dei template utilizzando l'interfaccia a riga di comando Firebase e le API di backend Remote Config.

È previsto un limite totale di 300 versioni archiviate per tutta la durata per tipo di modello (300 modelli client e 300 modelli server), che include i numeri di versione archiviati per i modelli eliminati. Se pubblichi più di 300 versioni di modelli per tipo di modello durante il ciclo di vita di un progetto, le versioni meno recenti vengono eliminate, mantenendo un massimo di 300 versioni di quel tipo.

Ogni volta che aggiorni i parametri, Remote Config crea un nuovo template Remote Config con controllo delle versioni e archivia il template precedente come una versione che puoi recuperare o di cui puoi eseguire il rollback in base alle tue esigenze. I numeri di versione vengono incrementati in sequenza a partire dal valore iniziale memorizzato da Remote Config. Tutti i modelli includono un campo version come mostrato, contenente i metadati relativi a quella versione specifica.

Puoi eliminare i modelli Remote Config in base alle tue esigenze nella pagina DevOps e coinvolgimento > Remote Config > Cronologia delle modifiche della console Firebase.

Gestisci le versioni del template Remote Config

Questa sezione descrive come gestire le versioni del template Remote Config.

Per maggiori dettagli su come creare, modificare e salvare i modelli in modo programmatico, consulta Modifica Remote Config in modo programmatico.

Elenca tutte le versioni archiviate del template Remote Config

Puoi recuperare un elenco di tutte le versioni archiviate del template Remote Config. Per farlo:

Console Firebase

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Parametri.

  2. Seleziona l'icona "orologio" visualizzata in alto a destra.

    Si apre la pagina Cronologia delle modifiche, che elenca tutte le versioni dei modelli memorizzate in un menu a elenco a destra.

    I dettagli visualizzati per ogni versione archiviata includono informazioni sull'origine delle modifiche, ovvero se provengono dalla console Firebase, dall'API REST, da un rollback o se si tratta di modifiche incrementali derivanti da un salvataggio forzato del template.

Interfaccia a riga di comando Firebase 

firebase remoteconfig:versions:list

Utilizza l'opzione --limit per limitare il numero di versioni restituite. Passa "0" per recuperare tutte le versioni.

Node.js

function listAllVersions() {
admin.remoteConfig().listVersions()
.then((listVersionsResult) => {
  console.log("Successfully fetched the list of versions");
  listVersionsResult.versions.forEach((version) => {
    console.log('version', JSON.stringify(version));
  });
})
.catch((error) => {
  console.log(error);
});
}

Java

ListVersionsPage page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
while (page != null) {
  for (Version version : page.getValues()) {
    System.out.println("Version: " + version.getVersionNumber());
  }
  page = page.getNextPage();
}

// Iterate through all versions. This will still retrieve versions in batches.
page = FirebaseRemoteConfig.getInstance().listVersionsAsync().get();
for (Version version : page.iterateAll()) {
  System.out.println("Version: " + version.getVersionNumber());
}

REST

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

L'elenco dei modelli include i metadati di tutte le versioni archiviate, tra cui l'ora dell'aggiornamento, l'utente che lo ha eseguito e il modo in cui è stato eseguito. Ecco un esempio di elemento version:

{
  "versions": [{
    "version_number": "6",
    "update_time": "2022-05-12T02:38:54Z",
    "update_user": {
      "name": "Jane Smith",
      "email": "jane@developer.org",
      "imageUrl": "https://lh3.googleusercontent.com/a-/..."
    },
    "description": "One small change on the console",
    "origin": "CONSOLE",
    "update_type": "INCREMENTAL_UPDATE"
  }]
}

Recupera una versione specifica del template Remote Config

Puoi recuperare qualsiasi versione archiviata specifica del template Remote Config. Ecco come recuperare una versione del modello memorizzata:

Console Firebase

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Cronologia delle modifiche.

  2. Per impostazione predefinita, la pagina mostra il modello attualmente attivo. Per visualizzare una versione diversa, selezionala nel riquadro dei dettagli a destra.

  3. Visualizza una differenza dettagliata tra il modello attivo e qualsiasi altra versione archiviata passando il mouse sopra il menu contestuale di qualsiasi versione non selezionata e selezionando Confronta con la versione selezionata.

Interfaccia a riga di comando Firebase 

firebase remoteconfig:get -v VERSION_NUMBER

Se vuoi, puoi scrivere l'output in un file specificato con -o, FILENAME.

Node.js

Passa getTemplate senza argomenti per recuperare l'ultima versione del template oppure utilizza getTemplateAtVersion per recuperare una versione specifica.

// Get template version: 6
admin.remoteConfig().getTemplateAtVersion('6')
.then((template) => {
console.log("Successfully fetched the template with ETag: " + template.etag);
})
.catch((error) => {
console.log(error);
});

Java

Template template = FirebaseRemoteConfig.getInstance().getTemplateAtVersionAsync(versionNumber).get();
// See the ETag of the fetched template.
System.out.println("Successfully fetched the template with ETag: " + template.getETag());

REST

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

Il parametro URL ?version_number è valido solo per le operazioni GET; non puoi utilizzarlo per specificare i numeri di versione per gli aggiornamenti. Una richiesta GET simile senza il parametro ?version_number recupererebbe il modello attivo corrente.

Esegui il rollback a una versione archiviata specifica del template Remote Config

Puoi eseguire il rollback a qualsiasi versione archiviata del template. Ecco come eseguire il rollback di un modello:

Console Firebase

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Cronologia delle modifiche.

  2. Individua il pulsante di opzione in alto a destra nella pagina per le versioni precedenti del modello idonee per il rollback.

  3. Fai clic e conferma questa opzione solo se hai la certezza di voler eseguire il rollback a quella versione e utilizzare questi valori immediatamente per tutte le app e tutti gli utenti.

Interfaccia a riga di comando Firebase 

firebase remoteconfig:rollback -v VERSION_NUMBER

Node.js

// Roll back to template version: 6
admin.remoteConfig().rollback('6')
  .then((template) => {
    console.log("Successfully rolled back to template version 6.");
    console.log("New ETag: " + template.etag);
  })
  .catch((error) => {
    console.log('Error trying to rollback:', e);
  })

Java

try {
  Template template = FirebaseRemoteConfig.getInstance().rollbackAsync(versionNumber).get();
  System.out.println("Successfully rolled back to template version: " + versionNumber);
  System.out.println("New ETag: " + template.getETag());
} catch (ExecutionException e) {
  if (e.getCause() instanceof FirebaseRemoteConfigException) {
    FirebaseRemoteConfigException rcError = (FirebaseRemoteConfigException) e.getCause();
    System.out.println("Error trying to rollback template.");
    System.out.println(rcError.getMessage());
  }
}

REST

Per eseguire il rollback a un template Remote Config archiviato, invia un HTTP POST con il metodo personalizzato :rollback e, nel corpo della richiesta, la versione specifica da applicare. Ad esempio:

curl --compressed -D headers -H "Authorization: Bearer token" -H "Content-Type: application/json" -X POST https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:rollback -d '{"version_number": 6}'

La risposta contiene i contenuti del template archiviato ora attivo, con i metadati della nuova versione.

Tieni presente che questa operazione di rollback crea di fatto una nuova versione numerata. Ad esempio, il rollback dalla versione 10 alla versione 6 crea di fatto una nuova copia della versione 6, che differisce dall'originale solo per il numero di versione, che è 11. La versione 6 originale viene comunque archiviata, supponendo che non abbia raggiunto la scadenza, e la versione 11 diventa il template attivo.

Elimina un modello Remote Config

Puoi eliminare i template Remote Config utilizzando la console Firebase. Ecco come eliminare un modello:

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Parametri.

  2. Fai clic su Cronologia delle modifiche.

  3. Passa al modello che vuoi eliminare, fai clic su Altro, quindi seleziona Elimina.

  4. Quando ti viene richiesto di confermare l'eliminazione, fai clic su Elimina.

Scarica e pubblica i modelli Remote Config

Scarica e pubblica i modelli Remote Config per integrarli nei tuoi sistemi di controllo del codice sorgente e di build, automatizzare gli aggiornamenti della configurazione e mantenere sincronizzati parametri e valori in più progetti.

Puoi scaricare il modello Remote Config attualmente attivo in modo programmatico o dalla console Firebase. Puoi quindi aggiornare il file JSON esportato e pubblicarlo nello stesso progetto o in un progetto nuovo o esistente.

Ad esempio, supponiamo che tu abbia più progetti che rappresentano diverse fasi del ciclo di vita dello sviluppo software, come ambienti di sviluppo, test, gestione temporanea e produzione. In questo caso, puoi promuovere un modello completamente testato dal tuo ambiente di gestione temporanea all'ambiente di produzione scaricandolo dal progetto di gestione temporanea e pubblicandolo nel progetto di produzione.

Puoi anche utilizzare questo metodo per eseguire la migrazione delle configurazioni da un progetto a un altro o per compilare un nuovo progetto con parametri e valori di un progetto esistente.

I parametri e i valori parametro creati specificamente come varianti in un esperimento A/B Testing non sono inclusi nei modelli esportati.

Per esportare e importare i modelli Remote Config:

  1. Scarica il modello Remote Config corrente.
  2. Convalida il template Remote Config.
  3. Pubblica il modello Remote Config.

Scarica il modello Remote Config attuale

Utilizza quanto segue per scaricare il modello Remote Config attivo in formato JSON:

Console Firebase

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Parametri o Condizioni.

  2. Apri il Menu e seleziona Scarica il file di configurazione attuale.

  3. Quando richiesto, fai clic su Scarica file di configurazione, scegli la posizione in cui vuoi salvare il file, quindi fai clic su Salva.

Interfaccia a riga di comando Firebase 

firebase remoteconfig:get -o filename

Node.js

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);
      });
}

Java

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

REST

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

Questo output comando restituisce il payload JSON in un file e le intestazioni (incluso l'ETag) in un file headers separato.

Convalida il modello Remote Config

Puoi convalidare gli aggiornamenti dei template prima di pubblicarli utilizzando Firebase Admin SDK o l'API REST. I template vengono convalidati anche quando tenti di pubblicarli dall'interfaccia a riga di comando Firebase o dalla console Firebase.

Il processo di convalida del modello 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.

Node.js

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);
      });
}

Java

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());
  }
}

REST

Convalida gli aggiornamenti del modello aggiungendo il parametro URL ?validate_only=true alla richiesta di pubblicazione:

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?validate_only=true -d @filename

Se il modello è stato convalidato correttamente, il comando curl restituisce il modello JSON inviato e, nel file headers salvato, troverai uno stato HTTP/2 200 e un ETag aggiornato con il suffisso -0. Se il tuo modello non è stato convalidato, riceverai l'errore di convalida nella risposta JSON e il file headers conterrà una risposta diversa da 200 (e nessun ETag).

Pubblica il modello Remote Config

Dopo aver scaricato un modello, apportato le modifiche necessarie ai contenuti JSON e averlo convalidato, puoi pubblicarlo in un progetto.

La pubblicazione di un template sostituisce l'intero template di configurazione esistente con il file aggiornato e incrementa di uno la versione del template. Poiché l'intera configurazione viene sostituita, se elimini un parametro dal file JSON e lo pubblichi, il parametro viene eliminato dal server e non è più disponibile per i client.

Dopo la pubblicazione, le modifiche ai parametri e ai valori sono immediatamente disponibili per le app e gli utenti. Se necessario, puoi eseguire il rollback a una versione precedente.

Utilizza i seguenti comandi per pubblicare il template:

Console Firebase

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Parametri o Condizioni.

  2. Apri il Menu e seleziona Pubblica da un file.

  3. Quando richiesto, fai clic su Sfoglia, vai al file Remote Config che vuoi pubblicare, selezionalo e fai clic su Seleziona.

  4. Firebase convalida il file. Se la convalida ha esito positivo, fai clic su Pubblica per rendere la configurazione immediatamente disponibile per le tue app e i tuoi utenti.

Node.js

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);
      });
}

Java

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());
  }
}

REST

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

Per questo comando curl, puoi specificare i contenuti utilizzando il carattere "@" seguito dal nome file.

Le personalizzazioni e le condizioni di Remote Config sono incluse nei modelli scaricati, pertanto è importante tenere presente le seguenti limitazioni quando si tenta di pubblicare in un progetto diverso:

  • Le personalizzazioni non possono essere importate da un progetto all'altro.

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

  • Le condizioni possono essere importate da un progetto all'altro, 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 hai un parametro Remote Config che utilizza una condizione che specifica un valore della piattaforma iOS, il modello può essere pubblicato in un altro progetto, perché i valori della piattaforma sono gli stessi per qualsiasi progetto. Tuttavia, se contiene una condizione che si basa su un ID app o un segmento di pubblico utente specifico che non esiste nel progetto di destinazione, la convalida non andrà a buon fine.

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

Scarica i valori predefiniti del modello Remote Config

Poiché l'app potrebbe non essere sempre connessa a internet, devi configurare i valori predefiniti dell'app lato client per tutti i parametri Remote Config. Inoltre, dovresti sincronizzare periodicamente i valori predefiniti del client dell'app e i valori dei parametri predefiniti del backend Remote Config, perché potrebbero cambiare nel tempo.

Come descritto nei link specifici per la piattaforma alla fine di questa sezione, puoi impostare manualmente questi valori predefiniti nella tua app oppure puoi semplificare questa procedura scaricando i file che contengono solo le coppie chiave-valore per tutti i parametri e i relativi valori predefiniti nel modello Remote Config attivo. Puoi quindi includere questo file nel tuo progetto e configurare l'app in modo che importi questi valori.

Puoi scaricare questi file in formato XML per le app per Android, in formato plist (property list) per le app per iOS e in formato JSON per le app web.

Scarica periodicamente i valori predefiniti di Remote Config prima di ogni nuova release dell'app per assicurarti che l'app e il backend di Remote Config rimangano sincronizzati.

Ecco come scaricare un file contenente i valori predefiniti del modello:

REST

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

Utilizza XML, PLIST o JSON come valore format, a seconda del formato file che vuoi scaricare.

Console Firebase

  1. Nella console Firebase, vai alla pagina DevOps e coinvolgimento > Remote Config > Parametri.

  2. Apri il Menu e seleziona Scarica valori predefiniti.

  3. Quando richiesto, fai clic sul pulsante di opzione corrispondente al formato file che vuoi scaricare, quindi fai clic su Scarica file.

Per saperne di più sull'importazione dei valori predefiniti di Remote Config nella tua app, consulta: