ModelliTemplates

PanoramicaOverview

I modelli consentono alle applicazioni client di specificare il formato esatto delle notifiche da ricevere.Templates enable a client application to specify the exact format of the notifications it wants to receive. Mediante i modelli, le app possono ottenere diversi vantaggi, fra cui i seguenti:Using templates, an app can realize several different benefits, including the following :

  • Un back-end indipendente dalla piattaformaA platform-agnostic backend
  • Notifiche personalizzatePersonalized notifications
  • Indipendenza dalla versione del clientClient-version independence
  • Localizzazione sempliceEasy localization

In questa sezione vengono forniti due esempi dettagliati di come utilizzare modelli per inviare notifiche indipendenti dalla piattaforma destinate a i dispositivi di tutte le piattaforme e per personalizzare la notifica di trasmissione per ciascun dispositivo.This section provides two in-depth examples of how to use templates to send platform-agnostic notifications targeting all your devices across platforms, and to personalize broadcast notification to each device.

Utilizzo di modelli multipiattaformaUsing templates cross-platform

Il metodo standard per inviare notifiche push consiste nell'inviare, per ciascuna notifica, uno specifico payload dei servizi di notifica della piattaforma (WNS, servizio APN).The standard way to send push notifications is to send, for each notification that is to be sent, a specific payload to platform notification services (WNS, APNS). Per inviare un avviso al servizio APN, ad esempio, il payload è un oggetto Json nel formato seguente:For example, to send an alert to APNS, the payload is a Json object of the following form:

{"aps": {"alert" : "Hello!" }}

Per inviare un messaggio di avviso popup simile in un'applicazione di Windows Store, il payload XML è il seguente:To send a similar toast message on a Windows Store application, the XML payload is as follows:

<toast>
  <visual>
    <binding template=\"ToastText01\">
      <text id=\"1\">Hello!</text>
    </binding>
  </visual>
</toast>

È possibile creare payload simili per MPNS (Windows Phone) e piattaforme GCM (Android).You can create similar payloads for MPNS (Windows Phone) and GCM (Android) platforms.

Tale requisito impone al back-end dell'app la produzione di payload diversi per ciascuna piattaforma e di fatto rende il back-end responsabile di parte del livello di presentazione dell'app.This requirement forces the app backend to produce different payloads for each platform, and effectively makes the backend responsible for part of the presentation layer of the app. Alcuni dei problemi riguardano la localizzazione e i layout grafici (soprattutto per applicazioni di Windows Store che comprendono notifiche per vari tipi di riquadri).Some concerns include localization and graphical layouts (especially for Windows Store apps that include notifications for various types of tiles).

La funzionalità del modello degli Hub di notifica consente a un'app client di creare registrazioni speciali, denominate registrazioni con modello, comprendenti un modello, oltre al set di tag.The Notification Hubs template feature enables a client app to create special registrations, called template registrations, which include, in addition to the set of tags, a template. La funzionalità del modello Hub di notifica consente a un'app client di associare i dispositivi con i modelli, indipendentemente dall'utilizzo di installazioni (scelta consigliata) o di registrazioni.The Notification Hubs template feature enables a client app to associate devices with templates whether you are working with Installations (preferred) or Registrations. Dati gli esempi di payload precedenti, le sole informazioni indipendenti dalla piattaforma consistono nel messaggio di avviso effettivo (Hello!).Given the preceding payload examples, the only platform-independent information is the actual alert message (Hello!). Un modello è un set di istruzioni per l'Hub di notifica circa la modalità di formattazione di un messaggio indipendente dalla piattaforma per la registrazione di una determinata app client.A template is a set of instructions for the Notification Hub on how to format a platform-independent message for the registration of that specific client app. Nell'esempio precedente, il messaggio indipendente dalla piattaforma consiste in una singola proprietà: message = Hello!.In the preceding example, the platform independent message is a single property: message = Hello!.

Nell'immagine seguente viene illustrato il processo indicato in precedenza:The following picture illustrates the above process:

Il modello per la registrazione dell'app client iOS è il seguente:The template for the iOS client app registration is as follows:

{"aps": {"alert": "$(message)"}}

Il modello corrispondente per l'applicazione client di Windows Store è:The corresponding template for the Windows Store client app is:

<toast>
    <visual>
        <binding template=\"ToastText01\">
            <text id=\"1\">$(message)</text>
        </binding>
    </visual>
</toast>

Si noti che il messaggio effettivo viene sostituito dall'espressione $(message).Notice that the actual message is substituted for the expression $(message). Tale espressione indica all'Hub di notifica, ogni volta che viene inviato un messaggio a quella particolare registrazione, di creare un messaggio successivo, commutandolo nel valore comune.This expression instructs the Notification Hub, whenever it sends a message to this particular registration, to build a message that follows it and switches in the common value.

Se si utilizza il modello di installazione, la chiave dei "modelli" di installazione contiene un JSON composto da più modelli.If you are working with Installation model, the installation “templates” key holds a JSON of multiple templates. Se si utilizza il modello di registrazione, l'applicazione client può creare più registrazioni per poter utilizzare più modelli: ad esempio, un modello per i messaggi di avviso e un modello per gli aggiornamenti dei riquadri.If you are working with Registration model, the client application can create multiple registrations in order to use multiple templates; for example, a template for alert messages and a template for tile updates. Inoltre, le applicazioni client possono unire registrazioni native (registrazioni senza modello) e registrazioni con modello.Client applications can also mix native registrations (registrations with no template) and template registrations.

L'Hub di notifica invia una notifica per ciascun modello senza considerare se appartengono alla stessa app client.The Notification Hub sends one notification for each template without considering whether they belong to the same client app. Questo comportamento può essere utilizzato per convertire notifiche indipendenti dalla piattaforma in più notifiche.This behavior can be used to translate platform-independent notifications into more notifications. Ad esempio, lo stesso messaggio indipendente dalla piattaforma all'Hub di notifica può essere facilmente convertito in un avviso popup e in un aggiornamento del riquadro, senza essere rilevato dal back-end.For example, the same platform independent message to the Notification Hub can be seamlessly translated in a toast alert and a tile update, without requiring the backend to be aware of it. Si noti che alcune piattaforme (ad esempio, iOS) potrebbero comprimere più notifiche allo stesso dispositivo se queste vengono inviate in un breve periodo di tempo.Note that some platforms (for example, iOS) might collapse multiple notifications to the same device if they are sent in a short period of time.

Utilizzo di modelli per la personalizzazioneUsing templates for personalization

Un altro vantaggio derivante dall'utilizzo di modelli è la possibilità di utilizzare gli Hub di notifica per eseguire la personalizzazione delle notifiche per registrazione.Another advantage to using templates is the ability to use Notification Hubs to perform per-registration personalization of notifications. Si consideri ad esempio un'app meteo che visualizza un riquadro sulle condizioni meteorologiche relative a un luogo specifico.For example, consider a weather app that displays a tile with the weather conditions at a specific location. Un utente può scegliere tra gradi Celsius o Fahrenheit e una previsione singola o di cinque giorni.A user can choose between Celsius or Fahrenheit degrees, and a single or five-day forecast. Mediante i modelli, ciascuna installazione dell'app client può registrare il formato richiesto (1 giorno in gradi Celsius 1 giorno in gradi Fahrenheit, 5 giorni in gradi Celsius, 5 giorni in gradi Fahrenheit), e far sì che il back-end invii un unico messaggio contenente tutte le informazioni necessarie per compilare i modelli (ad esempio una previsione di cinque giorni con gradi Celsius e Fahrenheit).Using templates, each client app installation can register for the format required (1-day Celsius, 1-day Fahrenheit, 5-days Celsius, 5-days Fahrenheit), and have the backend send a single message that contains all the information required to fill those templates (for example, a five-day forecast with Celsius and Fahrenheit degrees).

Il modello per la previsione di un giorno in gradi Celsius è il seguente:The template for the one-day forecast with Celsius temperatures is as follows:

<tile>
  <visual>
    <binding template="TileWideSmallImageAndText04">
      <image id="1" src="$(day1_image)" alt="alt text"/>
      <text id="1">Seattle, WA</text>
      <text id="2">$(day1_tempC)</text>
    </binding>  
  </visual>
</tile>

Il messaggio inviato all'Hub di notifica contiene tutte le proprietà seguenti:The message sent to the Notification Hub contains all the following properties:

day1_imageday1_imageday2_imageday2_imageday3_imageday3_imageday4_imageday4_imageday5_imageday5_image
day1_tempCday1_tempCday2_tempCday2_tempCday3_tempCday3_tempCday4_tempCday4_tempCday5_tempCday5_tempC
day1_tempFday1_tempFday2_tempFday2_tempFday3_tempFday3_tempFday4_tempFday4_tempFday5_tempFday5_tempF

Utilizzando questo modello, il back-end invia solo un unico messaggio senza dover memorizzare opzioni di personalizzazione specifiche per gli utenti dell'app.By using this pattern, the backend only sends a single message without having to store specific personalization options for the app users. Nell'immagine seguente viene illustrato tale scenario:The following picture illustrates this scenario:

Come registrare i modelliHow to register templates

Per la registrazione dei modelli mediante il modello di installazione (scelta consigliata) o il modello di registrazione, vedere Gestione delle registrazioni.To register with templates using the Installation model (preferred), or the Registration model, see Registration Management.

Linguaggio di espressione dei modelliTemplate expression language

I modelli sono limitati ai formati di documento XML o JSON.Templates are limited to XML or JSON document formats. Inoltre, è possibile inserire solo le espressioni in particolari punti: ad esempio, attributi dei nodi o valori per il formato XML, valori delle proprietà di stringa per il formato JSON.Also, you can only place expressions in particular places; for example, node attributes or values for XML, string property values for JSON.

Nella tabella seguente viene descritto il linguaggio consentito nei modelli:The following table shows the language allowed in templates:

EspressioneExpression DescrizioneDescription
$(prop)$(prop) Riferimento a una proprietà di evento con il nome specificato.Reference to an event property with the given name. I nomi delle proprietà non distinguono tra maiuscole e minuscole.Property names are not case-sensitive. Questa espressione viene risolta nel valore di testo della proprietà o in una stringa vuota se la proprietà non è presente.This expression resolves into the property’s text value or into an empty string if the property is not present.
$(prop, n)$(prop, n) Come in precedenza, ma il testo viene esplicitamente troncato dopo n caratteri, ad esempio $(title, 20) tronca il contenuto della proprietà del riquadro dopo 20 caratteri.As above, but the text is explicitly clipped at n characters, for example $(title, 20) clips the contents of the title property at 20 characters.
.(prop, n).(prop, n) Come in precedenza, ma vengono aggiunti tre punti alla fine del testo troncato.As above, but the text is suffixed with three dots as it is clipped. La dimensione totale della stringa troncata e del suffisso non supera n caratteri.The total size of the clipped string and the suffix does not exceed n characters. .(title, 20) con una proprietà di input "Questa è la riga del titolo" restituisce Questa è la riga....(title, 20) with an input property of “This is the title line” results in This is the title...
%(prop)%(prop) È simile a $(name), a eccezione del fatto che l'output è codificato in formato URI.Similar to $(name) except that the output is URI-encoded.
#(prop)#(prop) Utilizzata nei modelli JSON (ad esempio, per modelli iOS e Android).Used in JSON templates (for example, for iOS and Android templates).

Questa funzione opera esattamente come l'espressione $(prop) specificata in precedenza, salvo quando viene utilizzata nei modelli JSON (ad esempio, nei modelli Apple).This function works exactly the same as $(prop) previously specified, except when used in JSON templates (for example, Apple templates). In questo caso, se questa funzione non è racchiusa tra "{','}", ad esempio 'myJsonProperty' : '#(name)', e restituisce un numero in formato Javascript, ad esempio regexp: (0|([1-9][0-9]))(.[0-9]+)?((e|E)(+|-)?[0-9]+)?, l'output JSON sarà un numero.In this case, if this function is not surrounded by “{‘,’}” (for example, ‘myJsonProperty’ : ‘#(name)’), and it evaluates to a number in Javascript format, for example, regexp: (0|([1-9][0-9]))(.[0-9]+)?((e|E)(+|-)?[0-9]+)?, then the output JSON is a number.

Ad esempio, ' badge : '#(name)' diventa 'badge' : 40 (e non '40').For example, ‘badge : ‘#(name)’ becomes ‘badge’ : 40 (and not ‘40‘).
'text' o "text"‘text’ or “text” Valore letterale.A literal. I valori letterali contengono testo arbitrario racchiuso tra virgolette singole o doppie.Literals contain arbitrary text enclosed in single or double quotes.
expr1 + expr2expr1 + expr2 Operatore di concatenazione che unisce due espressioni in una singola stringa.The concatenation operator joining two expressions into a single string.

Il formato delle espressioni può essere uno dei precedenti.The expressions can be any of the preceding forms.

Quando si utilizza la concatenazione, l'intera espressione deve essere racchiusa tra parentesi graffe {}.When using concatenation, the entire expression must be surrounded with {}. Ad esempio, {$(prop) + ' - ' + $(prop2)}.For example, {$(prop) + ‘ - ’ + $(prop2)}. |

Ad esempio, il modello XML seguente non è valido:For example, the following is not a valid XML template:

<tile>
  <visual>
    <binding $(property)>
      <text id="1">Seattle, WA</text>
    </binding>  
  </visual>
</tile>

Come spiegato in precedenza, quando si utilizza la concatenazione, le espressioni devono essere racchiuse tra parentesi graffe.As explained above, when using concatenation, expressions must be wrapped in curly brackets. Ad esempio:For example:

<tile>
  <visual>
    <binding template="ToastText01">
      <text id="1">{'Hi, ' + $(name)}</text>
    </binding>  
  </visual>
</tile>