Modelli e controllo delle versioni di Remote Config

I modelli Remote Config sono insiemi di parametri e condizioni in formato JSON che hai creato per il tuo progetto Firebase. Puoi creare modelli client, da cui la tua app recupera i valori, e modelli server, da cui i client server possono recuperare i valori.

Modifichi e gestisci il modello utilizzando la console Firebase, che mostra i contenuti del modello in formato grafico nelle schede schede Parametri e Condizioni.

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

Ecco un esempio di file modello 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 con la console Firebase:

• Elenco di tutte le versioni del modello memorizzate
• Recuperare una versione specifica
• Esegui il rollback a una versione specifica del client
• Eliminare i modelli Remote Config dalla pagina Cronologia modifiche

Puoi anche elencare, recuperare e ripristinare i modelli utilizzando l'interfaccia a riga di comando di Firebase e le API di backend Remote Config.

È previsto un limite totale di 300 versioni archiviate a vita 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 la durata 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 modello Remote Config con controllo delle versioni e memorizza il modello precedente come una versione che puoi recuperare o ripristinare in base alle necessità. I numeri di versione vengono incrementati in sequenza a partire dal valore iniziale memorizzato da Remote Config. Come mostrato, tutti i modelli includono un campo version contenente i metadati relativi a quella versione specifica.

Puoi eliminare i modelli Remote Config in base alle esigenze dalla pagina Cronologia delle modifiche nella console Remote Config.

Gestire le versioni del modello Remote Config

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

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

Elenca tutte le versioni memorizzate del modello Remote Config

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

firebase remoteconfig:versions:list

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

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

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

L'elenco dei modelli include i metadati di tutte le versioni archiviate, tra cui l'ora dell'aggiornamento, l'utente che l'ha eseguito e la modalità di esecuzione. Ecco un esempio di elemento versione:

```json
{
  "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"
  }]
}
```

Recuperare una versione specifica del modello Remote Config

Puoi recuperare qualsiasi versione specifica memorizzata del modello Remote Config. Per recuperare una versione memorizzata del modello:

firebase remoteconfig:get -v VERSION_NUMBER

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

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

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

Eseguire il rollback a una versione specifica memorizzata del modello Remote Config

Puoi eseguire il rollback a qualsiasi versione memorizzata del modello. Per eseguire il rollback di un modello:

firebase remoteconfig:rollback -v VERSION_NUMBER

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

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

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

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

Eliminare un modello di Remote Config

Puoi eliminare i modelli Remote Config dalla console Firebase. Per eliminare un modello Remote Config:

1. Passa al modello da eliminare, fai clic su more_vertAltro e seleziona Elimina.

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

Scaricare e pubblicare 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 Puoi quindi aggiornare il file JSON esportato e pubblicarlo nello stesso progetto oppure in un progetto nuovo o esistente.

Supponiamo che tu abbia più progetti che rappresentano diverse fasi del ciclo di vita di sviluppo del software, come ambienti di sviluppo, test, gestione temporanea e produzione. In questo caso, puoi promuovere un modello completamente testato dall'ambiente di staging all'ambiente di produzione scaricandolo dal progetto di staging 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 appositamente 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 di configurazione Remote Config corrente.
2. Convalida il Remote Config modello.
3. Pubblica il modello Remote Config.

Scaricare il modello Remote Config attuale

Utilizza il seguente comando per scaricare il modello Remote Config attivo in formato JSON:

firebase remoteconfig:get -o filename

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

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

Convalida il modello Remote Config

Il processo di convalida del modello verifica la presenza di errori quali chiavi duplicate per parametri e condizioni, nomi di condizioni non validi o condizioni inesistenti oppure ETag con formato errato. Ad esempio, una richiesta contenente un numero di chiavi superiore a quello consentito (2000) restituirebbe il messaggio di errore Param count too large.

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

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

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 modello sostituisce l'intero modello di configurazione esistente con il file aggiornato e incrementa la versione del modello di un'unità. 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 modello:

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

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

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

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

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

• Le condizioni possono essere importate da un progetto all'altro, ma tieni presente che i 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 pari a 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 pubblico di utenti specifico che non esiste nel progetto di destinazione, la convalida non andrà a buon fine.

• Se il modello 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é la tua app potrebbe non essere sempre connessa a internet, devi configurare i valori predefiniti dell'app lato client per tutti i parametri Remote Config. Devi anche sincronizzare periodicamente i valori predefiniti del client dell'app e i valori predefiniti dei parametri del backend Remote Config, perché potrebbero cambiare nel tempo.

Come descritto nei link specifici della piattaforma alla fine di questa sezione, puoi impostare manualmente questi valori predefiniti nella tua app oppure puoi semplificare questo processo scaricando 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 per importare questi valori.

Puoi scaricare questi file in formato XML per le app per Android, in formato elenco di proprietà (plist) per le app per iOS e in formato JSON per le app web.

Ti consigliamo di scaricare 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.

Per scaricare un file contenente i valori predefiniti del modello:

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

Per ulteriori informazioni sull'importazione dei valori predefiniti di Remote Config nella tua app, consulta:

• Impostare i valori predefiniti dei parametri in-app per Android

• Impostare i valori predefiniti dei parametri in-app per iOS

• Impostare i valori predefiniti dei parametri in-app per il web

• Impostare i valori predefiniti dei parametri in-app per Unity

• Impostare i valori predefiniti dei parametri in-app per C++