Catch up on highlights from Firebase at Google I/O 2023. Learn more

Modelli di configurazione remota e controllo delle versioni

Il modello Remote Config è il set lato server di parametri e condizioni in formato JSON che hai creato per il tuo progetto Firebase. Puoi modificare e gestire il modello utilizzando la console Firebase, che visualizza i contenuti del modello in formato grafico nelle schede Parametri e Condizioni . Puoi anche utilizzare le API back-end di Remote Config o l' interfaccia a riga di comando di Firebase per modificare e gestire la tua configurazione.

Ecco un esempio di file modello:

  {
    "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"
    }
  }

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 ripristinare 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.

Con la console di Firebase, l'interfaccia a riga di comando di Firebase o le API back-end di Remote Config, puoi eseguire queste attività di gestione delle versioni:

  • Elenca tutte le versioni del modello archiviate
  • Recupera una versione specifica
  • Eseguire il rollback a una versione specifica

Mentre gestisci i modelli Remote Config, tieni presente la soglia di scadenza: il modello Remote Config attivo attualmente utilizzato dalla tua app non scade; tuttavia, se viene sostituito da un aggiornamento, la versione precedente verrà conservata solo per 90 giorni, dopodiché scadrà e non sarà più recuperabile. C'è anche un limite totale di 300 versioni memorizzate. Se desideri archiviare o ripristinare un modello al di fuori di tali limiti, salvalo e archivialo manualmente.

Gestisci le versioni del modello Remote Config

Questa sezione descrive come gestire le versioni del modello Remote Config. Per ulteriori dettagli su come creare, modificare e salvare i modelli a livello di codice, vedere Modificare la configurazione remota a livello di codice .

Elenca tutte le versioni archiviate del modello Remote Config

È possibile recuperare un elenco di tutte le versioni archiviate del modello Remote Config. Per esempio:

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

Giava

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

RIPOSO

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

Console Firebase

Nella scheda Parametri selezionare l'icona "orologio" visualizzata in alto a destra. Questo apre la pagina Cronologia delle modifiche che elenca tutte le versioni del modello memorizzate in un menu elenco a destra.

I dettagli visualizzati per ciascuna versione archiviata includono informazioni sul fatto che le modifiche siano state originate con la console, con l'API REST, da un rollback o se si trattasse di modifiche incrementali da un salvataggio forzato del modello.

interfaccia a riga di comando di Firebase

firebase remoteconfig:versions:list

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

L'elenco dei modelli include i metadati per tutte le versioni archiviate, inclusa l'ora dell'aggiornamento, l'utente che lo ha effettuato e se è stato effettuato tramite la console o l'API REST. Ecco un esempio di un 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 modello Remote Config

È possibile recuperare qualsiasi versione archiviata specifica del modello Remote Config. Per esempio:

Node.js

Passa getTemplate() senza argomenti per recuperare l'ultima versione del modello o per recuperare una versione specifica, usa getTemplateAtVersion() .

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

Giava

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

RIPOSO

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 usarlo per specificare i numeri di versione per gli aggiornamenti. Una richiesta get simile senza il parametro ?version_number recupererebbe il modello attivo corrente.

Console Firebase

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

Puoi visualizzare una differenza dettagliata della versione attualmente selezionata e di qualsiasi altra versione memorizzata passando con il mouse sopra il menu di scelta rapida per qualsiasi versione non selezionata e selezionando Confronta con la versione selezionata.

interfaccia a riga di comando di Firebase

firebase remoteconfig:get -v VERSION_NUMBER

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

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

Puoi eseguire il rollback a qualsiasi versione archiviata del modello. Per esempio:

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

Giava

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

RIPOSO

Per eseguire il rollback a un modello Remote Config archiviato, emettere un POST HTTP con il metodo personalizzato :rollback e, nel corpo della richiesta, la versione specifica da applicare. Per 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.

Console Firebase

Per le versioni precedenti del modello idonee per il rollback, in alto a destra nella pagina Cronologia modifiche viene visualizzato un pulsante di opzione per eseguire il rollback a tale versione. Fai clic e conferma solo se sei sicuro di voler tornare a quella versione e utilizzare immediatamente quei valori per tutte le app e gli utenti.

interfaccia a riga di comando di Firebase

firebase remoteconfig:rollback -v VERSION_NUMBER

Si noti 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 fatto che il suo numero di versione è 11. La versione 6 originale è ancora memorizzata, supponendo che non abbia raggiunto la sua scadenza, e la versione 11 diventa il modello attivo.

Scarica e pubblica i modelli Remote Config

Scarica e pubblica i modelli Remote Config per integrarli nel controllo del codice sorgente e nei sistemi di compilazione, automatizza gli aggiornamenti della configurazione e mantieni i parametri e i valori sincronizzati su più progetti.

Puoi scaricare il modello Remote Config attualmente attivo a livello di programmazione o dalla console Firebase. È quindi possibile aggiornare il file JSON esportato e pubblicarlo nello stesso progetto oppure pubblicarlo in un progetto nuovo o esistente.

Supponiamo che tu abbia più progetti che rappresentano diverse fasi del ciclo di vita dello sviluppo software, come ambienti di sviluppo, test, staging e produzione. In questo caso, puoi promuovere un modello completamente testato dal tuo ambiente di staging al tuo ambiente di produzione scaricandolo dal tuo progetto di staging e pubblicandolo nel tuo progetto di produzione.

È inoltre possibile utilizzare questo metodo per migrare le configurazioni da un progetto a un altro o popolare un nuovo progetto con parametri e valori da un progetto stabilito.

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 esportare e importare i modelli Remote Config:

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

Scarica il modello di configurazione remota corrente

Puoi scaricare il modello Remote Config corrente e attivo a livello di programmazione o utilizzando la console Firebase.

Utilizzare i seguenti comandi per scaricare il modello Remote Config attivo in formato JSON:

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

Giava

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

RIPOSO

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

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

Console Firebase

  1. Dalla scheda Remote Config Parameters or Conditions , apri il menu e seleziona Download current config file .
  2. Quando richiesto, fai clic su Scarica file di configurazione , scegli la posizione in cui desideri salvare il file, quindi fai clic su Salva .

interfaccia a riga di comando di Firebase

firebase remoteconfig:get -o filename

Convalida il modello Remote Config

Puoi convalidare gli aggiornamenti del modello prima di pubblicarli utilizzando l'SDK Firebase Admin o l'API REST. I modelli vengono convalidati anche quando tenti di pubblicare dall'interfaccia a riga di comando di 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);
      });
}

Giava

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

RIPOSO

Convalida gli aggiornamenti del modello aggiungendo il parametro URL ?validate_only=true alla tua 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 tuo modello è stato convalidato correttamente, il comando curl restituisce il modello JSON che hai 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 tuo file headers conterrà una risposta diversa da 200 (e nessun ETag).

Pubblica il modello Remote Config

Dopo aver scaricato un modello, aver apportato le modifiche necessarie al contenuto 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 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 tue app e i tuoi utenti. Se necessario, puoi eseguire il rollback a una versione precedente .

Utilizza i seguenti comandi per pubblicare il tuo modello:

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

Giava

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

RIPOSO

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 il contenuto utilizzando il carattere "@", seguito dal nome del file.

Console Firebase

  1. Dalla scheda Parametri o condizioni di configurazione remota , apri il menu e seleziona Pubblica da un file .
  2. Quando richiesto, fare clic su Sfoglia , individuare e selezionare il file Remote Config che si desidera pubblicare, quindi fare clic su Seleziona .
  3. Il file verrà convalidato e, in caso di successo, puoi fare clic su Pubblica per rendere immediatamente disponibile la configurazione alle tue app e ai tuoi utenti.

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.

Scarica le impostazioni predefinite 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 di Remote Config. È inoltre necessario sincronizzare periodicamente i valori predefiniti del client dell'app e i valori dei parametri predefiniti del back-end di Remote Config, perché potrebbero cambiare nel tempo.

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

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

Ti consigliamo di scaricare periodicamente le impostazioni predefinite di Remote Config prima di qualsiasi nuova versione dell'app per assicurarti che la tua app e il back-end di Remote Config rimangano sincronizzati.

Per scaricare un file che contiene i valori predefiniti del modello:

RIPOSO

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 di file che desideri scaricare.

Console Firebase

  1. Nella scheda Parametri , apri il menu e seleziona Scarica valori predefiniti .
  2. Quando richiesto, fai clic sul pulsante di opzione che corrisponde al formato di file che desideri scaricare, quindi fai clic su Scarica file .

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