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 del server possono recuperare i valori.

Questa sezione illustra i modelli di client. Per scoprire di più sui modelli specifici per il server, fai clic su Modelli di server.

Puoi modificare e gestire il modello utilizzando la console Firebase, che mostra i contenuti del modello in formato grafico nelle schede Le schede Parametri e Condizioni.

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

Ecco un esempio di file modello di server:

{
  "parameters": {
    "preamble_prompt": {
      "defaultValue": {
        "value": "You are a helpful assistant who knows everything there is to know about Firebase! "
      },
      "description": "Add this prompt to the user's prompt",
      "valueType": "STRING"
    },
    "model_name": {
      "defaultValue": {
        "value": "gemini-pro-test"
      },
      "valueType": "STRING"
    },
    "generation_config": {
      "defaultValue": {
        "value": "{\"temperature\": 0.9, \"maxOutputTokens\": 2048, \"topP\": 0.9, \"topK\": 20}"
      },
      "valueType": "JSON"
    },
  },
  "version": {
    "versionNumber": "19",
    "isLegacy": true
  }
}

Puoi eseguire queste attività di gestione delle versioni con la console Firebase:

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

Esiste un limite totale di 300 versioni archiviate per tutta la vita utile per tipo di modello (300 modelli client e 300 modelli server), inclusi i numeri di versione archiviati per i modelli eliminati. Se pubblichi più di 300 versioni di modelli per tipo di modello durante la vita di un progetto, le versioni precedenti 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 versione e archivia il modello precedente come versione che puoi recuperare o a cui eseguire il rollback in base alle esigenze. I numeri di versione vengono incrementati in sequenza 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 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 tuo Remote Config modello.

Elenca tutte le versioni archiviate del modello Remote Config

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

Console Firebase

Nella scheda Parametri, seleziona l'icona a forma di orologio visualizzata in alto a destra. Si apre la pagina Cronologia delle modifiche che elenca tutte le versioni del modello memorizzate in un menu di elenco a destra.

I dettagli visualizzati per ogni versione archiviata includono informazioni su se le modifiche hanno avuto origine dalla console, dall'API REST, da un rollback o se si tratta di modifiche incrementali da un salvataggio forzato del modello.

Firebase CLI 

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 <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 lo ha creato e la modalità di creazione. 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 di un modello memorizzato:

Console Firebase

Per impostazione predefinita, il riquadro dei dettagli nella scheda Cronologia delle modifiche mostra il modello attivo corrente. Per visualizzare i dettagli di un'altra versione nell'elenco, selezionala dal menu a destra.

Puoi visualizzare una differenza dettagliata tra la versione attualmente selezionata e qualsiasi altra versione archiviata passando il mouse sopra il menu contestuale di una versione non selezionata e selezionando Confronta con la versione selezionata.

Firebase CLI 

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 la versione più recente del modello oppure usa 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 <var>token</var>" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/<var>my-project-id</var>/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 modello Remote Config

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

Console Firebase

Per le versioni precedenti del modello idonee per il rollback, in alto a destra nella pagina Cronologia delle modifiche viene visualizzato un pulsante di opzione per eseguire il rollback a quella versione. Fai clic e conferma 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.

Firebase CLI 

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 modello Remote Config archiviato, esegui una richiesta POST HTTP con il metodo personalizzato :rollback e, nel corpo della richiesta, la versione specifica da applicare. Ad esempio:

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}'

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

Tieni presente che questa operazione di rollback crea effettivamente 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 11. La versione originale 6 è ancora archiviata, a condizione che non abbia raggiunto la scadenza, e la versione 11 diventa il modello attivo.

Eliminare un modello Remote Config

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

1. Nella pagina Remote Config Parametri, fai clic su Cronologia delle modifiche.

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

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

Scaricare e pubblicare modelli Remote Config

Scarica e pubblica modelli Remote Config per integrarli nel tuo sistema di controllo del codice sorgente e di compilazione, automatizzare gli aggiornamenti della configurazione e mantenere sincronizzati parametri e valori in più progetti.

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

Supponiamo che tu abbia più progetti che rappresentano diverse fasi del ciclo di vita dello sviluppo software, come gli ambienti di sviluppo, test, gestione temporanea e produzione. In questo caso, puoi promuovere un modello completamente testato dall'ambiente di staging a quello 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 all'altro o compilare un nuovo progetto con i parametri e i valori di un progetto esistente.

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

Per esportare e importare modelli Remote Config:

  1. Scarica il modello di configurazione Remote Config attuale.
  2. Convalida il modello Remote Config.
  3. Pubblica il modello Remote Config.

Scarica il modello Remote Config corrente

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

Console Firebase

  1. Nella scheda Remote Config Parametri o condizioni, apri Menu e seleziona Scarica file di configurazione corrente.
  2. Quando richiesto, fai clic su Scarica file di configurazione, scegli la posizione in cui vuoi salvare il file e poi fai clic su Salva.

Firebase CLI 

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 comando genera il payload JSON in un file e le intestazioni (inclusa l'ETag) in un file headers separato.

Convalida il modello Remote Config

Puoi convalidare gli aggiornamenti dei modelli prima di pubblicarli utilizzandoFirebase Admin SDK o l'API REST. I modelli vengono convalidati anche quando provi a pubblicarli dalla CLI Firebase o dalla console Firebase.

La procedura di convalida del modello verifica la presenza di errori come chiavi duplicate per parametri e condizioni, nomi di condizioni non validi o inesistenti o ETag con formattazione errata. Ad esempio, una richiesta contenente più del numero consentito di chiavi (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 nessuna ETag).

Pubblica il modello Remote Config

Dopo aver scaricato un modello, apportato le modifiche necessarie ai contenuti JSON e effettuato la convalida, 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 uno. 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:

Console Firebase

  1. Dalla scheda Remote Config Parametri o condizioni, apri il Menu e seleziona Pubblica da un file.
  2. Quando richiesto, fai clic su Sfoglia, vai al fileRemote Config che vuoi pubblicare e selezionalo, poi fai clic su Seleziona.
  3. Il file verrà convalidato e, se la convalida va a buon fine, puoi fare 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.

Remote Config Le personalizzazioni e le condizioni 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 nel tuo progetto hai attivato le personalizzazioni e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non in un altro progetto, 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 essere presenti 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 specifico che non esiste nel progetto di destinazione, la convalida non andrà a buon fine.

  • Se il modello che prevedi di pubblicare contiene condizioni basate su Google Analytics, Analytics deve essere attivato 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, devi sincronizzare periodicamente i valori predefiniti del client dell'app e i valori predefiniti dei parametri del backend di Remote Config, in quanto possono 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 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 progetto e configurare l'app per importare questi valori.

Puoi scaricare questi file in formato XML per le app per Android, in formato elenco 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:

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 del file che vuoi scaricare.

Console Firebase

  1. Nella scheda Parametri, apri il Menu e seleziona Scarica valori predefiniti.
  2. Quando richiesto, fai clic sul pulsante di opzione corrispondente al formato file che vuoi scaricare e poi su Scarica file.

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