Modifica Remote Config in modo programmatico

Questo documento descrive come leggere e modificare in modo programmatico l'insieme di parametri e condizioni in formato JSON noto come Remote Config modello. In questo modo puoi apportare modifiche al modello nel backend che l'app client può recuperare utilizzando la libreria client.

Utilizzando l'API REST Remote Config o gli Admin SDKs descritti in questa guida, puoi evitare di gestire il modello nella console Firebase per integrare direttamente le modifiche Remote Config nei tuoi processi. Ad esempio, con Remote Config API di backend puoi:

• Pianificare gli aggiornamentiRemote Config. Utilizzando le chiamate API in combinazione con un cron job, puoi modificare i valori Remote Config in base a una pianificazione regolare.
• Importare in batch i valori di configurazione per eseguire la transizione in modo efficiente dal tuo sistema proprietario a Firebase Remote Config.

• Utilizzare Remote Config con Cloud Functions for Firebase, modificando i valori nell'app in base agli eventi che si verificano lato server. Ad esempio, puoi utilizzare Remote Config per promuovere una nuova funzionalità nella tua app e poi disattivare automaticamente la promozione una volta rilevato che un numero sufficiente di persone ha interagito con la nuova funzionalità.

  

Le sezioni seguenti di questa guida descrivono le operazioni che puoi eseguire con le Remote Config API di backend. Per esaminare il codice che esegue queste attività tramite l'API REST, consulta una di queste app di esempio:

• Guida rapida all'API REST di Firebase Remote Config per Java
• Guida rapida all'API REST di Firebase Remote Config per Node.js
• Guida rapida all'API REST di Firebase Remote Config per Python

Modificare Remote Config utilizzando l'SDK Firebase Admin

L'Admin SDK è un insieme di librerie server che ti consentono di interagire con Firebase da ambienti con privilegi. Oltre a eseguire gli aggiornamenti di Remote Config, l'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 saperne di più sui prerequisiti e sulla configurazione di Admin SDK, consulta Aggiungere l'SDK Firebase Admin al server.

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

Inizializzare l'SDK e autorizzare le richieste API

Quando inizializzi il 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.

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

Recuperare il modello Remote Config attuale

Quando lavori con i modelli Remote Config, tieni presente che sono versionati 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. Per saperne di più, consulta Modelli e controllo delle versioni.

Puoi utilizzare le API di backend per recuperare la versione attiva corrente del Remote Config modello in formato JSON.

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

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

Modificare i parametri di Remote Config

Puoi modificare e aggiungere in modo programmatico i parametri Remote Config e i gruppi di parametri. Ad esempio, a un gruppo di parametri esistente denominato "new_menu" potresti 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 di modificare i valori predefiniti, i valori condizionali e le descrizioni. In tutti i casi, devi pubblicare esplicitamente il modello dopo aver apportato le modifiche.

Modificare le condizioni di Remote Config

Puoi modificare e aggiungere in modo programmatico le Remote Config condizioni e i valori condizionali. 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, devi pubblicare esplicitamente il modello dopo aver apportato le modifiche.

Le API di backend Remote Config forniscono diverse condizioni e operatori di confronto che puoi utilizzare per modificare il comportamento e l'aspetto della tua app. Per saperne di più sulle condizioni e sugli operatori supportati per queste condizioni, consulta il riferimento alle espressioni condizionali.

Convalidare il modello Remote Config

Facoltativamente, puoi convalidare gli aggiornamenti prima di pubblicarli, come mostrato di seguito:

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

Questa procedura di convalida verifica la presenza di errori come chiavi duplicate per parametri e condizioni, nomi di condizioni non validi o condizioni inesistenti o 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.

Pubblicare il modello Remote Config

Dopo aver recuperato un modello e averlo modificato 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 superiore di uno rispetto al modello sostituito.

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

Le personalizzazioni e le condizioni di Remote Config sono incluse nei modelli scaricati, quindi è importante essere a conoscenza delle 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 tuo progetto e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non puoi pubblicarlo in un progetto diverso 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 paramet0/} 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.Remote Config 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 modello che intendi pubblicare contiene condizioni che si basano su Google Analytics, Analytics deve essere attivato 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());
  }
}

Modificare Remote Config utilizzando l'API REST

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

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

I progetti Firebase supportano i service account Google, che puoi utilizzare per chiamare le API server Firebase dal server dell'app o dall'ambiente attendibile. Se sviluppi codice in locale o esegui il deployment della tua applicazione on-premise, puoi utilizzare le credenziali ottenute utilizzando questo service account per autorizzare le richieste del server.

Puoi visualizzare tutti i service account per il tuo progetto Firebase nella settings Impostazioni > Service account tab.

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

Per generare un file della chiave privata per il tuo service account:

1. Nella console Firebase, vai alla scheda settings Impostazioni > Service account.

2. Fai clic su Genera nuova chiave privata, quindi conferma facendo clic su Genera chiave.

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

Quando autorizzi tramite un service account, hai due opzioni per fornire le credenziali alla tua applicazione. Puoi impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS oppure puoi passare esplicitamente il percorso della chiave del service account nel codice. La prima opzione è più sicura ed è vivamente consigliata.

Per impostare la variabile di ambiente:

Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del file JSON contenente la chiave del service account. Questa variabile si applica solo alla sessione di shell corrente, quindi se apri una nuova sessione, imposta di nuovo 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, le credenziali predefinite dell'applicazione (ADC) sono in grado di determinare implicitamente le tue credenziali, consentendoti di utilizzare le credenziali del service account durante il test o l'esecuzione in ambienti non Google.

Utilizza le 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

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

Una volta scaduto il 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 versionati 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. Per saperne di più, consulta Modelli e controllo delle versioni.

Recuperare il modello Remote Config attuale

Puoi utilizzare le API di backend per recuperare la versione attiva corrente del Remote Config modello in formato JSON.

I parametri e i valori dei parametri creati appositamente come varianti in un A/B Testing esperimento 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

Convalidare il modello Remote Config

Facoltativamente, puoi convalidare gli aggiornamenti prima di pubblicarli. Convalida gli aggiornamenti del modello aggiungendo alla 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.

Aggiornare il modello Remote Config

Dopo aver recuperato un modello e aver modificato 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 superiore di uno rispetto al modello sostituito.

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

Le personalizzazioni e le condizioni di Remote Config sono incluse nei modelli scaricati, quindi è importante essere a conoscenza delle 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 tuo progetto e scarichi e modifichi un modello, puoi pubblicarlo nello stesso progetto, ma non puoi pubblicarlo in un progetto diverso 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 paramet0/} 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.Remote Config 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 modello che intendi pubblicare contiene condizioni che si basano su Google Analytics, Analytics deve essere attivato 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

Puoi modificare in modo programmatico le condizioni Remote Config e i valori condizionali. Con l'API REST, devi modificare direttamente il modello per modificare le condizioni prima di pubblicarlo.

{
  "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 sopra riportate definiscono innanzitutto un insieme di condizioni, quindi definiscono i valori predefiniti e i valori dei parametri basati sulle condizioni (valori condizionali) per ogni parametro. Aggiunge anche una descrizione facoltativa per ogni elemento; come i commenti del codice, questi sono per l'utilizzo da parte degli sviluppatori e non vengono visualizzati nell'app. Viene fornito anche un ETag per il controllo delle versioni.

Le API di backend Remote Config forniscono diverse condizioni e operatori di confronto che puoi utilizzare per modificare il comportamento e l'aspetto della tua app. Per saperne di più sulle condizioni e sugli operatori supportati per queste condizioni, consulta il riferimento alle espressioni condizionali.

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 utilizzano questo progetto. Altri codici di stato indicano che il Remote Config modello esistente in precedenza è ancora attivo.

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

Utilizzo di ETag e aggiornamenti forzati

L'API REST Remote Config utilizza un tag di entità (ETag) per impedire condizioni di race e aggiornamenti sovrapposti alle risorse. Per saperne di più sugli ETag, consulta ETag - HTTP.

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

Puoi aggirare l'ETag e la protezione che fornisce forzando l'aggiornamento del modello Remote Config come segue: If-Match: * Tuttavia, questo approccio non è consigliato perché rischia di causare la perdita degli aggiornamenti al modello Remote Config se più client aggiornano 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 Firebase utenti della console.

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