Configurazione con passaggi

La configurazione con passaggi consente a un connettore di completare dinamicamente la configurazione del connettore in base alle risposte fornite dall'utente. Ad esempio, compilare un menu a discesa "Città" dopo aver selezionato un menu a discesa "Stato".

Requisiti

Questa guida presuppone che tu conosca già le configurazioni dei connettori della community. Consulta l'articolo su come definire la configurazione tramite getConfig per un ripasso.

Panoramica

La configurazione a passaggi prevede che Looker Studio chiami getConfig() più volte e il connettore restituisce ogni volta più domande di configurazione. Ogni chiamata a getConfig() includerà le risposte dell'utente all'ultima risposta di getConfig(). Questo processo continua a condizione che tu restituisca una risposta con setIsSteppedConfig(true).

Linee guida

Imposta setIsSteppedConfig(true) fino al completamento della configurazione

Looker Studio chiamerà getConfig() ripetutamente, purché setIsSteppedConfig(true) sia impostato.Una volta completata la configurazione, la risposta getConfig() finale dovrebbe impostare setIsSteppedConfig(false).

Imposta isDynamic(true) per le domande di configurazione che determinano le domande successive

Se un campo contrassegnato come isDynamic viene modificato dall'utente, le voci di configurazione successive verranno cancellate nell'interfaccia utente e l'utente dovrà configurare tutti i passaggi successivi. Ciò consente di assicurarsi che gli utenti non inviino una configurazione non valida.

Le risposte fornite dall'utente verranno trasmesse tramite request.configParams.

request.configParams sarà undefined per la prima richiesta getConfig() al connettore. Le richieste successive includeranno le risposte fornite dall'utente sotto forma di oggetto codificato dagli ID di configurazione o undefined se l'utente non fornisce risposte.

Esempio:

{
  state: 'CA',
  city: 'mountain_view'
}

Le configurazioni sono cumulative

È necessario aggiungere nuove domande di configurazione dopo quelle esistenti.

Le configurazioni non possono essere modificate

Se è stata posta in precedenza una domanda di configurazione, deve essere presente per tutte le chiamate successive. Ad esempio, se nella prima chiamata a getConfig() è stata posta la domanda di configurazione A, è necessario includere A in tutte le risposte future.

Le configurazioni sono idempotenti

Le chiamate a getConfig() con lo stesso configParams dovrebbero restituire la stessa configurazione.

Non è possibile eseguire l'override dei parametri dinamici

Looker Studio non consente la override dei parametri di configurazione dinamica.

Configurazioni di esempio

Menu a discesa dinamici

Questa prima domanda chiede all'utente di selezionare uno stato e poi fornisce dinamicamente un menu a discesa per le città in base allo stato selezionato.

var cc = DataStudioApp.createCommunityConnector();

function optionsForState(state) {
  switch (state) {
    case "IL": {
      return [["Chicago", "chicago"], ["Springfield", "springfield"]];
    }
    case "CA": {
      return [["Mountain View", "mountain_view"], ["Los Angeles", "los_angeles"]];
    }
    default: {
      cc.newUserError()
          .setText('You must either select "IL" or "CA"')
          .throwException();
    }
  }
}

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config.newSelectSingle()
      .setId("state")
      .setName("State")
  // Set isDynamic to true so any changes to State will clear the city
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel("Illinois").setValue("IL"))
      .addOption(config.newOptionBuilder().setLabel("California").setValue("CA"));

  if (!isFirstRequest) {
    var city = config.newSelectSingle()
        .setId("city")
        .setName("City");
    var cityOptions = optionsForState(configParams.state);
    cityOptions.forEach(function(labelAndValue) {
      var cityLabel = labelAndValue[0];
      var cityValue = labelAndValue[1];
      city.addOption(config.newOptionBuilder().setLabel(cityLabel).setValue(cityValue));
    });
  }
  return config.build();
}

Percorsi di diramazione

Verrà richiesta un'ulteriore domanda se il "Paese" selezionato è "Stati Uniti".

var cc = DataStudioApp.createCommunityConnector();

function getConfig(request) {
  var configParams = request.configParams;
  var isFirstRequest = configParams === undefined;
  var config = cc.getConfig();
  if (isFirstRequest) {
    config.setIsSteppedConfig(true);
  }

  config
      .newSelectSingle()
      .setId('country')
      .setName('Country')
  // Set isDynamic to true so any changes to Country will clear the state
  // selections.
      .setIsDynamic(true)
      .addOption(config.newOptionBuilder().setLabel('United States').setValue('USA'))
      .addOption(config.newOptionBuilder().setLabel('Canada').setValue('CA'));

  if (!isFirstRequest) {
    // validate a valid value was selected for configParams.country
    if (configParams.country === undefined) {
      cc.newUserError().setText('You must choose a country.').throwException();
    }
    switch (configParams.country) {
      case 'USA': {
        config
            .newSelectSingle()
            .setId('state')
            .setName('State')
            .addOption(config.newOptionBuilder().setLabel('New York').setValue('NY'))
            .addOption(config.newOptionBuilder().setLabel('Calfornia').setValue('CA'));
        break;
      }
      case 'CA': {
        // No additional configuration is needed for Canada.
        break;
      }
      default: {
        cc.newUserError()
            .setText('You must either select "CA" or "USA"')
            .throwException();
      }
    }
  }
  return config.build();
}