Konfiguracja krokowa

Konfiguracja krokowa umożliwia oprogramowaniu sprzęgającemu dynamiczne wypełnianie konfiguracji oprogramowania sprzęgającego na podstawie odpowiedzi udzielonych przez użytkowników. np. po wybraniu opcji „Stan” w menu „Miasto”.

Wymagania

W tym przewodniku zakładamy, że znasz już konfiguracje oprogramowania sprzęgającego społeczności. Jeśli chcesz odświeżyć swoją wiedzę, zobacz Definiowanie konfiguracji za pomocą getConfig.

Opis

Konfiguracja krokowa polega na tym, że Looker Studio wielokrotnie wywołuje funkcję getConfig(), a oprogramowanie sprzęgające za każdym razem zwraca więcej pytań dotyczących konfiguracji. Każde wywołanie funkcji getConfig() będzie obejmowało odpowiedzi użytkownika na ostatnią odpowiedź (getConfig()). Ten proces będzie kontynuowany, dopóki zwrócisz odpowiedź z atrybutem setIsSteppedConfig(true).

Wytyczne

Ustaw setIsSteppedConfig(true), dopóki nie zakończy się konfiguracja

Looker Studio będzie wielokrotnie wywoływać metodę getConfig(), dopóki ustawiona jest wartość setIsSteppedConfig(true).Po zakończeniu konfiguracji ostateczna odpowiedź getConfig() powinna ustawić wartość setIsSteppedConfig(false).

Ustaw isDynamic(true) na pytania konfiguracyjne, które określają później

Jeśli użytkownik zmieni pole oznaczone jako isDynamic, kolejne wpisy konfiguracji zostaną wyczyszczone w interfejsie, a użytkownik będzie musiał skonfigurować wszystkie kolejne kroki. Dzięki temu użytkownicy nie wysyłają nieprawidłowej konfiguracji.

Odpowiedzi użytkowników będą przekazywane przez request.configParams.

W przypadku pierwszego żądania getConfig() do oprogramowania sprzęgającego request.configParams wartość będzie undefined. Kolejne żądania będą zawierać odpowiedzi przekazane przez użytkownika w formie obiektu z uwzględnieniem identyfikatorów konfiguracji lub undefined, jeśli użytkownik nie odpowie.

Przykład:

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

Konfiguracje się sumują

Nowe pytania konfiguracyjne należy dodawać po istniejących.

Konfiguracje nie mogą być mutowane

Jeśli pytanie dotyczące konfiguracji zostało zadane wcześniej, powinno być obecne w przypadku wszystkich kolejnych wywołań. Jeśli na przykład w pierwszym wywołaniu funkcji getConfig() zostało zadane pytanie konfiguracyjne A, wszystkie przyszłe odpowiedzi powinny zawierać pytanie A.

Konfiguracje są idempotentne

Wywołania funkcji getConfig() z tą samą wartością configParams powinny zwracać tę samą konfigurację.

Parametrów dynamicznych nie można zastąpić

Looker Studio nie zezwala na zastępowanie dynamicznych parametrów konfiguracji.

Przykładowe konfiguracje

Dynamiczne menu

Pierwsze pytanie zachęca użytkownika do wybrania województwa, a następnie dynamicznie wyświetla menu z miastem odpowiednie do tego stanu.

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

Ścieżki rozgałęzienia

Jeśli wybrany kraj to „USA”, pojawi się dodatkowe pytanie.

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