Aggiungere codice per la sperimentazione nella tua app

  • Articolo

Dopo aver creato un progetto e definito le variabili remote nel Centro per i partner, è possibile aggiornare il codice nell'app UWP (Universal Windows Platform) per:

  • Ricevere i valori delle variabili remote dal Centro per i partner.
  • Usare le variabili remote per configurare le esperienze utente dell'app.
  • Registrare nel Centro per i partner eventi che indicano quando gli utenti hanno visualizzato l'esperimento ed eseguito un'azione desiderata (anche denominata conversione).

Per aggiungere questo comportamento all'app, si useranno le API fornite da Microsoft Store Services SDK.

Le sezioni seguenti descrivono il processo generale di recupero delle variazioni per l'esperimento e di registrazione degli eventi nel Centro per i partner. Dopo aver scritto il codice dell'app per la sperimentazione, è possibile definire un esperimento nel Centro per i partner. Per una procedura dettagliata che illustra il processo end-to-end di creazione ed esecuzione di un esperimento, vedere Creare ed eseguire il primo esperimento con test A/B.

Nota

Alcune API di sperimentazione in Microsoft Store Services SDK usano il modello asincrono per recuperare dati dal Centro per i partner. Ciò significa che una parte dell'esecuzione di questi metodi può avvenire dopo che i metodi vengono richiamati, pertanto l'interfaccia utente dell'app potrebbe non rispondere finché le operazioni non vengono completate. Il modello asincrono richiede che l'app usi la parola chiave async e l'operatore await quando chiama le API, come illustrato negli esempi di codice in questo articolo. Per convenzione, i metodi asincroni terminano con Async.

Configurare il progetto

Per iniziare, installare Microsoft Store Services SDK nel computer di sviluppo e aggiungere i riferimenti necessari al progetto.

  1. Installare Microsoft Store Services SDK.
  2. Aprire il progetto in Visual Studio.
  3. In Esplora soluzioni espandere il nodo del progetto, fare clic con il pulsante destro del mouse su Riferimenti e scegliere Aggiungi riferimento.
  4. In Gestione riferimenti espandere Universal Windows e fare clic su Estensioni.
  5. Nell'elenco degli SDK selezionare la casella di controllo accanto a Microsoft Engagement Framework e fare clic su OK.

Nota

Gli esempi di codice in questo articolo presuppongono che il file di codice includa istruzioni using per gli spazi dei nomi System.Threading.Tasks e Microsoft.Services.Store.Engagement.

Ottenere i dati delle varianti e registrare l'evento di visualizzazione per l'esperimento

Nel progetto individuare il codice per la funzionalità che si desidera modificare nell'esperimento. Aggiungere il codice che recupera i dati per una variante, usare questi dati per modificare il comportamento della funzionalità che si sta testando, quindi registrare l'evento di visualizzazione per l'esperimento nel servizio di test A/B nel Centro per i partner.

Il codice specifico necessario dipenderà dall'app, ma l'esempio seguente illustra il processo di base. Per un esempio di codice completo, vedere Creare ed eseguire il primo esperimento con test A/B.

private StoreServicesExperimentVariation variation;
private StoreServicesCustomEventLogger logger;

// Assign this variable to the project ID for your experiment from Dev Center.
// The project ID shown below is for example purposes only.
private string projectId = "F48AC670-4472-4387-AB7D-D65B095153FB";

private async Task InitializeExperiment()
{
    // Get the current cached variation assignment for the experiment.
    var result = await StoreServicesExperimentVariation.GetCachedVariationAsync(projectId);
    variation = result.ExperimentVariation;

    // Refresh the cached variation assignment if necessary.
    if (result.ErrorCode != StoreServicesEngagementErrorCode.None || result.ExperimentVariation.IsStale)
    {
        result = await StoreServicesExperimentVariation.GetRefreshedVariationAsync(projectId);

        if (result.ErrorCode == StoreServicesEngagementErrorCode.None)
        {
            variation = result.ExperimentVariation;
        }
    }

    // Get the remote variable named "buttonText" and assign the value
    // to the button.
    var buttonText = variation.GetString("buttonText", "Grey Button");
    await button.Dispatcher.RunAsync(
        Windows.UI.Core.CoreDispatcherPriority.Normal,
        () =>
        {
            button.Content = buttonText;
        });

    // Log the view event named "userViewedButton" to Dev Center.
    if (logger == null)
    {
        logger = StoreServicesCustomEventLogger.GetDefault();
    }

    logger.LogForVariation(variation, "userViewedButton");
}

I passaggi seguenti descrivono in dettaglio le parti importanti di questo processo.

  1. Dichiarare un oggetto StoreServicesExperimentVariation che rappresenta l'assegnazione della variante corrente e un oggetto StoreServicesCustomEventLogger che si userà per registrare gli eventi di visualizzazione e conversione nel Centro per i partner.

    private StoreServicesExperimentVariation variation;
private StoreServicesCustomEventLogger logger;

  2. Dichiarare una variabile di stringa assegnata all'ID progetto per l'esperimento che si desidera recuperare.

    Nota

    Si ottiene un ID progetto quando si crea un progetto nel Centro per i partner. L'ID progetto mostrato di seguito è solo a scopo esemplificativo.

    private string projectId = "F48AC670-4472-4387-AB7D-D65B095153FB";

  3. Ottenere l'assegnazione della variante memorizzata nella cache corrente per l'esperimento chiamando il metodo statico GetCachedVariationAsync e passare l'ID progetto per l'esperimento al metodo. Questo metodo restituisce un oggetto StoreServicesExperimentVariationResult che fornisce accesso all'assegnazione della variante tramite la proprietà ExperimentVariation.

    var result = await StoreServicesExperimentVariation.GetCachedVariationAsync(projectId);
variation = result.ExperimentVariation;

  4. Controllare la proprietà IsStale per determinare se l'assegnazione della variante memorizzata nella cache deve essere aggiornata con un'assegnazione della variante remota ottenuta dal server. Se deve essere aggiornata, chiamare il metodo GetRefreshedVariationAsync statico per controllare la disponibilità di un'assegnazione della variante aggiornata nel server e aggiornare la variante locale memorizzata nella cache.

    if (result.ErrorCode != StoreServicesEngagementErrorCode.None || result.ExperimentVariation.IsStale)
{
    result = await StoreServicesExperimentVariation.GetRefreshedVariationAsync(projectId);

    if (result.ErrorCode == StoreServicesEngagementErrorCode.None)
    {
        variation = result.ExperimentVariation;
    }
}

  5. Usare i metodi GetBoolean, GetDouble, GetInt32 o GetString dell'oggetto StoreServicesExperimentVariation per ottenere i valori per l'assegnazione della variante. In ogni metodo, il primo parametro è il nome della variante che si desidera recuperare (è lo stesso nome di una variante immessa nel Centro per i partner). Il secondo parametro è il valore predefinito che il metodo deve restituire se non è in grado di recuperare il valore specificato dal Centro per i partner (ad esempio, in assenza di connettività di rete) e non è disponibile una versione della variante memorizzata nella cache.

    L'esempio seguente usa GetString per ottenere una variabile denominata buttonText e specifica un valore di variabile predefinito Grey Button.

    var buttonText = variation.GetString("buttonText", "Grey Button");

  6. Nel codice usare i valori delle variabili per modificare il comportamento della funzionalità che si sta testando. Ad esempio, il codice seguente assegna il valore buttonText al contenuto di un pulsante nell'app. Questo esempio presuppone che il pulsante sia già stato definito altrove nel progetto.

    await button.Dispatcher.RunAsync(
    Windows.UI.Core.CoreDispatcherPriority.Normal,
    () =>
    {
        button.Content = buttonText;
    });

  7. Infine registrare l'evento di visualizzazione per l'esperimento nel servizio di test A/B nel Centro per i partner. Inizializzare il campo logger a un oggetto StoreServicesCustomEventLogger e chiamare il metodo LogForVariation. Passare l'oggetto StoreServicesExperimentVariation che rappresenta l'assegnazione della variante corrente (questo oggetto fornisce contesto sull'evento al Centro per i partner) e il nome dell'evento di visualizzazione per l'esperimento. Deve corrispondere al nome dell'evento di visualizzazione immesso per l'esperimento nel Centro per i partner. Il codice deve registrare l'evento di visualizzazione quando l'utente inizia a visualizzare una variante che fa parte dell'esperimento.

    L'esempio seguente illustra come registrare un evento di visualizzazione denominato userViewedButton. L'obiettivo di questo esempio è ottenere che l'utente faccia clic su un pulsante nell'app, pertanto l'evento di visualizzazione viene registrato dopo che l'app recupera i dati della variante (in questo caso, il testo del pulsante) e li assegna al contenuto del pulsante.

    if (logger == null)
{
    logger = StoreServicesCustomEventLogger.GetDefault();
}

logger.LogForVariation(variation, "userViewedButton");

Registrare gli eventi di conversione nel Centro per i partner

Quindi, aggiungere il codice che registra gli eventi di conversione nel servizio di test A/B nel Centro per i partner. Il codice deve registrare un evento di conversione quando l'utente raggiunge un obiettivo per l'esperimento. Il codice specifico necessario dipenderà dall'app, di seguito sono riportati i passaggi generali. Per un esempio di codice completo, vedere Creare ed eseguire il primo esperimento con test A/B.

  1. Nel codice eseguito quando l'utente raggiunge un obiettivo per uno degli scopi dell'esperimento, chiamare nuovamente il metodo LogForVariation e passare l'oggetto StoreServicesExperimentVariation e il nome di un evento di conversione per l'esperimento. Deve corrispondere a uno dei nomi degli eventi di conversione immessi per l'esperimento nel Centro per i partner.

    L'esempio seguente registra un evento di conversione denominato userClickedButton dal gestore dell'evento Click per un pulsante. In questo esempio l'obiettivo dell'esperimento è ottenere che l'utente faccia clic sul pulsante.

    private void button_Click(object sender, RoutedEventArgs e)
{
    if (logger == null)
    {
        logger = StoreServicesCustomEventLogger.GetDefault();
    }

    logger.LogForVariation(variation, "userClickedButton");
}

Passaggi successivi

Dopo aver scritto il codice dell'esperimento nell'app, è possibile svolgere i passaggi seguenti:

  1. Definire l'esperimento nel Centro per i partner. Creare un esperimento che definisce gli eventi di visualizzazione, gli eventi di conversione e le varianti univoche per il test A/B.
  2. Eseguire e gestire l'esperimento nel Centro per i partner.