Usare l'API di Azure Mobile Engagement in un'applicazione WebUse the Azure Mobile Engagement API in a web application

Questo documento è un'aggiunta al documento Integrare Azure Mobile Engagement in un'applicazione Web.This document is an addition to the document that tells you how to integrate Mobile Engagement in a web application. Offre informazioni approfondite su come usare l'API di Azure Mobile Engagement per segnalare le statistiche dell'applicazione.It provides in-depth details about how to use the Azure Mobile Engagement API to report your application statistics.

L'API di Mobile Engagement viene messa a disposizione dall'oggetto engagement.agent .The Mobile Engagement API is provided by the engagement.agent object. L'alias predefinito di Azure Mobile Engagement Web SDK è engagement.The default Azure Mobile Engagement Web SDK alias is engagement. È possibile ridefinire l'alias dalla configurazione dell'SDK.You can redefine this alias from the SDK configuration.

Concetti relativi a Mobile EngagementMobile Engagement concepts

Le parti seguenti approfondiscono le informazioni contenute nell'articolo Concetti relativi ad Azure Mobile Engagement per la piattaforma Web.The following parts refine common Mobile Engagement concepts for the web platform.

Session e ActivitySession and Activity

Se l'utente resta inattivo per più di alcuni secondi tra due attività, la sequenza di attività dell'utente viene divisa in due sessioni distinte.If the user stays idle for more than a few seconds between two activities, the user's sequence of activities is split into two distinct sessions. Questi pochi secondi vengono chiamati timeout della sessione.These few seconds are called the session timeout.

Se l'applicazione Web non dichiara la fine delle attività utente chiamando la funzione engagement.agent.endActivity , il server di Mobile Engagement terminerà automaticamente la sessione utente entro tre minuti dalla chiusura della pagina dell'applicazione.If your web application doesn't declare the end of user activities by itself (by calling the engagement.agent.endActivity function), the Mobile Engagement server automatically expires the user session within three minutes after the application page is closed. Questo comportamento viene definito timeout della sessione del server.This is called the server session timeout.

Crash

I report automatici di eccezioni JavaScript non rilevate non vengono creati per impostazione predefinita.Automated reports of uncaught JavaScript exceptions are not created by default. È tuttavia possibile segnalare manualmente gli arresti anomali usando la funzione sendCrash. Vedere la sezione sulla segnalazione degli arresti anomali.However, you can report crashes manually by using the sendCrash function (see the section on reporting crashes).

Segnalazione di attivitàReporting activities

La segnalazione delle attività utente include il momento in cui un utente avvia una nuova attività e il momento in cui l'utente termina l'attività corrente.Reporting on user activity includes when a user starts a new activity, and when the user ends the current activity.

L'utente avvia una nuova attivitàUser starts a new activity

engagement.agent.startActivity("MyUserActivity");

È necessario chiamare startActivity() ogni volta che l'attività dell'utente cambia.You need to call startActivity() each time user activity changes. La prima chiamata a questa funzione avvia una nuova sessione utente.The first call to this function starts a new user session.

L'utente termina l'attività correnteUser ends the current activity

engagement.agent.endActivity();

È necessario chiamare endActivity() almeno una volta quando l'utente termina l'ultima attività.You need to call endActivity() at least once when the user finishes their last activity. In questo modo si indica a Mobile Engagement Web SDK che l'utente è attualmente inattivo e che la sessione utente deve essere chiusa allo scadere del timeout.This informs the Mobile Engagement Web SDK that the user is currently idle, and that the user session needs to be closed after the session timeout expires. Se si chiama startActivity() prima dello scadere del timeout, la sessione viene semplicemente ripresa.If you call startActivity() before the session timeout expires, the session is simply resumed.

Data l'assenza di una chiamata affidabile per il momento in cui la finestra dello strumento di navigazione viene chiusa, è spesso difficile o impossibile rilevare la fine delle attività utente all'interno di ambienti Web.Because there's no reliable call for when the navigator window is closed, it's often difficult or impossible to catch the end of user activities inside a web environment. Per questo motivo il server di Mobile Engagement termina automaticamente la sessione utente entro tre minuti dalla chiusura della pagina dell'applicazione.That's why the Mobile Engagement server automatically expires the user session within three minutes after the application page is closed.

Segnalazione di eventiReporting events

La segnalazione di eventi include eventi di sessione ed eventi autonomi.Reporting on events covers session events and standalone events.

Eventi di sessioneSession events

Gli eventi di sessione vengono in genere usati per segnalare le azioni eseguite da un utente durante la sua sessione.Session events usually are used to report the actions performed by a user during the user's session.

Esempio senza dati aggiuntivi:Example without extra data:

loginButton.onclick = function() {
  engagement.agent.sendSessionEvent('login');
  // [...]
}

Esempio con dati aggiuntivi:Example with extra data:

loginButton.onclick = function() {
  engagement.agent.sendSessionEvent('login', {user: 'alice'});
  // [...]
}

Eventi autonomiStandalone events

A differenza degli eventi di sessione, gli eventi autonomi possono verificarsi all'esterno del contesto di una sessione.Unlike session events, standalone events can occur outside the context of a session.

A tale scopo, usare engagement.agent.sendEvent invece di engagement.agent.sendSessionEvent.For that, use engagement.agent.sendEvent instead of engagement.agent.sendSessionEvent.

Segnalazione di erroriReporting errors

La segnalazione di errori include errori di sessione ed errori autonomi.Reporting on errors covers session errors and standalone errors.

Errori di sessioneSession errors

Gli errori di sessione vengono in genere usati per segnalare gli errori che hanno impatto sull'utente durante la sua sessione.Session errors usually are used to report the errors that have an impact on the user during the user's session.

Esempio senza dati aggiuntivi:Example without extra data:

var validateForm = function() {
  // [...]
  if (password.length < 6) {
    engagement.agent.sendSessionError('password_too_short');
  }
  // [...]
}

Esempio con dati aggiuntivi:Example with extra data:

var validateForm = function() {
  // [...]
  if (password.length < 6) {
    engagement.agent.sendSessionError('password_too_short', {length: 4});
  }
  // [...]
}

Errori autonomiStandalone errors

A differenza degli errori di sessione, gli errori autonomi possono verificarsi all'esterno del contesto di una sessione.Unlike session errors, standalone errors can occur outside the context of a session.

A tale scopo, usare engagement.agent.sendError invece di engagement.agent.sendSessionError.For that, use engagement.agent.sendError instead of engagement.agent.sendSessionError.

Segnalazione di processiReporting jobs

La segnalazione di processi include la segnalazione di errori ed eventi che si verificano durante un processo e la segnalazione di arresti anomali.Reporting on jobs covers reporting errors and events that occur during a job, and reporting crashes.

Esempio:Example:

Per monitorare una richiesta AJAX, usare il codice seguente:If you want to monitor an AJAX request, you'd use the following:

// [...]
xhr.onreadystatechange = function() {
  if (xhr.readyState == 4) {
  // [...]
    engagement.agent.endJob('publish');
  }
}
engagement.agent.startJob('publish');
xhr.send();
// [...]

Segnalazione di errori durante un processoReporting errors during a job

Gli errori possono essere correlati a un processo in esecuzione invece che alla sessione utente corrente.Errors can be related to a running job instead of to the current user session.

Esempio:Example:

Per segnalare un errore in caso di esito negativo di una richiesta AJAX:If you want to report an error if an AJAX request fails:

// [...]
xhr.onreadystatechange = function() {
  if (xhr.readyState == 4) {
    // [...]
    if (xhr.status == 0 || xhr.status >= 400) {
      engagement.agent.sendJobError('publish_xhr', 'publish', {status: xhr.status, statusText: xhr.statusText});
    }
    engagement.agent.endJob('publish');
  }
}
engagement.agent.startJob('publish');
xhr.send();
// [...]

Segnalazione di eventi durante un processoReporting events during a job

Gli eventi possono essere correlati a un processo in esecuzione invece che alla sessione utente corrente grazie alla funzione engagement.agent.sendJobEvent .Events can be related to a running job instead of to the current user session, thanks to the engagement.agent.sendJobEvent function.

Questa funzione opera esattamente come la funzione engagement.agent.sendJobError.This function works exactly like engagement.agent.sendJobError.

Segnalazione di arresti anomaliReporting crashes

Usare la funzione sendCrash per segnalare manualmente gli arresti anomali.Use the sendCrash function to report crashes manually.

L'argomento crashid è una stringa che identifica il tipo di arresto anomalo.The crashid argument is a string that identifies the type of crash. L'argomento crash è in genere l'analisi dello stack dell'arresto anomalo sotto forma di stringa.The crash argument usually is the stack trace of the crash as a string.

engagement.agent.sendCrash(crashid, crash);

Parametri aggiuntiviExtra parameters

È possibile collegare dati arbitrari a un evento, errore, attività o processo.You can attach arbitrary data to an event, error, activity, or job.

Questi dati possono essere qualsiasi oggetto JSON, ma non una matrice o un tipo primitivo.The data can be any JSON object (but not an array or primitive type).

Esempio:Example:

var extras = {"video_id": 123, "ref_click": "http://foobar.com/blog"};
engagement.agent.sendEvent("video_clicked", extras);

LimitiLimits

I limiti che si applicano ai parametri aggiuntivi riguardano le aree delle espressioni regolari per chiavi, tipi di valore e dimensioni.Limits that apply to extra parameters are in the areas of regular expressions for keys, value types, and size.

ChiaviKeys

Ogni chiave dell'oggetto deve corrispondere all'espressione regolare seguente:Each key in the object must match the following regular expression:

^[a-zA-Z][a-zA-Z_0-9]*

Questo significa che le chiavi devono iniziare con almeno una lettera seguita da lettere, cifre o caratteri di sottolineatura (_).This means that keys must start with at least one letter, followed by letters, digits, or underscores (_).

ValoriValues

I valori sono limitati a tipi string, number e boolean.Values are limited to string, number, and Boolean types.

DimensioneSize

I dati aggiuntivi sono limitati a 1.024 caratteri per chiamata, dopo che la chiamata è stata codificata in JSON da Mobile Engagement Web SDK.Extras are limited to 1,024 characters per call (after the Mobile Engagement Web SDK encodes it in JSON).

Segnalazione di informazioni sull'applicazioneReporting application information

È possibile segnalare manualmente le informazioni di traccia o qualsiasi altra informazione specifica dell'applicazione con la funzione sendAppInfo() .You can manually report tracking information (or any other application-specific information) by using the sendAppInfo() function.

Si noti che queste informazioni possono essere inviate in modo incrementale.Note that this information can be sent incrementally. Verrà mantenuto solo l'ultimo valore per una chiave specifica per un dispositivo specifico.Only the latest value for a specific key will be kept for a specific device.

Come per i dati aggiuntivi degli eventi, è possibile usare qualsiasi oggetto JSON per astrarre le informazioni sull'applicazione.Like event extras, you can use any JSON object to abstract application information. Si noti che le matrici o gli oggetti secondari vengono trattati come stringhe flat, usando la serializzazione JSON.Note that arrays or sub-objects are treated as flat strings (using JSON serialization).

Esempio:Example:

Di seguito è riportato un esempio di codice per inviare il sesso e la data di nascita dell'utente:Here is a code sample for sending the user's gender and birth date:

var appInfos = {"birthdate":"1983-12-07","gender":"female"};
engagement.agent.sendAppInfo(appInfos);

LimitiLimits

I limiti che si applicano alle informazioni sull'applicazione riguardano le aree delle espressioni regolari per chiavi e dimensioni.Limits that apply to application information are in the areas of regular expressions for keys, and size.

ChiaviKeys

Ogni chiave dell'oggetto deve corrispondere all'espressione regolare seguente:Each key in the object must match the following regular expression:

^[a-zA-Z][a-zA-Z_0-9]*

Questo significa che le chiavi devono iniziare con almeno una lettera seguita da lettere, cifre o caratteri di sottolineatura (_).This means that keys must start with at least one letter, followed by letters, digits, or underscores (_).

DimensioneSize

Le informazioni sull'applicazione sono limitate a 1.024 caratteri per chiamata, dopo che la chiamata è stata codificata in JSON da Mobile Engagement Web SDK.Application information is limited to 1,024 characters per call (after the Mobile Engagement Web SDK encodes it in JSON).

Nell'esempio precedente, il codice JSON inviato al server è lungo 44 caratteri:In the preceding example, the JSON sent to the server is 44 characters long:

{"birthdate":"1983-12-07","gender":"female"}