Configuration par étapes

La configuration par étapes permet à un connecteur d'y insérer de manière dynamique en fonction des réponses fournies par l'utilisateur. Par exemple, si vous indiquez une "Ville", menu déroulant après un « État » est sélectionné.

Conditions requises

Dans ce guide, nous partons du principe que vous connaissez déjà le connecteur de communauté. de configuration. Pour rappel, consultez la section Définir la configuration via getConfig.

Présentation

La configuration par étapes consiste à ce que Looker Studio appelle getConfig() plusieurs et votre connecteur renvoie à chaque fois plus de questions de configuration. Chaque l'appel à getConfig() inclut les réponses de l'utilisateur à la dernière getConfig() de réponse. Ce processus se poursuit tant que vous renvoyez une réponse avec setIsSteppedConfig(true)

Consignes

Définissez setIsSteppedConfig(true) jusqu'à ce que la configuration soit terminée

Looker Studio appellera getConfig() à plusieurs reprises tant que setIsSteppedConfig(true) est défini.Une fois la configuration terminée, l'état final La réponse getConfig() doit définir setIsSteppedConfig(false).

Définissez isDynamic(true) pour les questions de configuration qui détermineront les questions ultérieures.

Si un champ marqué isDynamic est modifié par l'utilisateur, les modifications suivantes entrées de configuration seront effacées dans l'interface utilisateur et l'utilisateur devra configurer toutes les étapes suivantes. Cela permet de s'assurer que les utilisateurs ne vous envoient pas configuration non valide.

Les réponses fournies par l'utilisateur seront transmises via request.configParams.

request.configParams sera undefined pendant getConfig() à votre connecteur. Les requêtes suivantes incluront les les réponses fournies par l'utilisateur sous la forme d'un objet associé aux ID de configuration ou undefined si l'utilisateur ne fournit aucune réponse.

Exemple :

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

Les configurations se cumulent

Les nouvelles questions de configuration doivent être ajoutées après les questions existantes.

Impossible de modifier les configurations

Si une question de configuration a été posée précédemment, elle doit être présente pour tous les appels suivants. Par exemple, si la question de configuration A est posée, lors du premier appel à getConfig(), A doit être inclus dans tous les futurs appels des réponses.

Les configurations sont idempotentes

Les appels à getConfig() avec le même configParams doivent renvoyer le même résultat configuration.

Impossible de remplacer les paramètres dynamiques

Looker Studio n'autorise pas les paramètres de configuration dynamique remplacée.

Exemples de configurations

Menus déroulants dynamiques

Cette première question invite l'utilisateur à sélectionner un état, puis fournit dynamiquement dans un menu déroulant de ville en fonction de l'État sélectionné.

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

Chemins d'embranchement

Une question supplémentaire s'affichera si le "pays" sélectionné est "USA".

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