通知中心模板Notification Hubs templates

模板可让客户端应用程序指定它想要接收的确切通知格式。Templates enable a client application to specify the exact format of the notifications it wants to receive. 通过使用模板,应用可获得多个不同优势,其中包括:Using templates, an app can realize several different benefits, including the following:

  • 平台不可知的后端A platform-agnostic backend
  • 个性化通知Personalized notifications
  • 客户端版本独立性Client-version independence
  • 易于本地化Easy localization

本部分提供两个深入的示例,介绍如何使用模板跨平台向所有设备发送与平台无关的通知,以及介绍如何针对每台设备对广播通知进行个性化设置。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.

使用跨平台模板Using templates cross-platform

发送推送通知的标准方法是向平台通知服务(WNS、APNS)发送要传出的每个通知的特定负载。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). 例如,要向 APNS 发送警报,有效负载将是以下格式的 JSON 对象:For example, to send an alert to APNS, the payload is a JSON object of the following form:

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

要在 Windows 应用商店应用程序中发送类似的 toast 消息,XML 负载将如下所示: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>

可以为 MPNS (Windows Phone) 和 Baidu (Android) 平台创建类似的有效负载。You can create similar payloads for MPNS (Windows Phone) and Baidu (Android) platforms.

此要求将强制应用后端针对每个平台生成不同的负载,并有效地使后端负责应用的表示层部分。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. 某些考虑因素包括本地化和图形布局(尤其针对 Windows 应用商店应用,其中包含不同磁贴类型的通知)。Some concerns include localization and graphical layouts (especially for Windows Store apps that include notifications for various types of tiles).

使用通知中心模板功能,客户端应用可以创建称为模板注册的特殊注册,其中除了包含标记集外,还包含一个模板。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. 无论使用安装(首选)还是注册,通知中心模板功能都能使客户端应用将设备与模板相关联。The Notification Hubs template feature enables a client app to associate devices with templates whether you are working with Installations (preferred) or Registrations. 在前面的负载示例中,唯一的与平台无关的信息就是实际警报消息 (Hello!)。Given the preceding payload examples, the only platform-independent information is the actual alert message (Hello!). 模板是一组指令,指示通知中心如何针对该特定客户端应用的注册来设置与平台无关的消息的格式。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. 在前面的示例中,与平台无关的消息是单个属性:message = Hello!In the preceding example, the platform-independent message is a single property: message = Hello!.

下图演示了该过程:The following picture illustrates the process:

显示跨平台模板使用过程的关系图

iOS 客户端应用注册的模板如下所示:The template for the iOS client app registration is as follows:

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

Windows 应用商店客户端应用的相应模板为:The corresponding template for the Windows Store client app is:

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

请注意,实际消息将替换表达式 $(message)。Notice that the actual message is substituted for the expression $(message). 每当通知中心向此特定注册发送消息时,此表达式将指示通知中心构建遵循此模板并用常用值替换的消息。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.

如果使用的是安装模型,则安装“templates”键会保存多个模板的 JSON。If you are working with Installation model, the installation “templates” key holds a JSON of multiple templates. 如果使用的是注册模型,则客户端应用程序可以创建多个注册以使用多个模板;例如,例如,用于警报消息的模板和用于磁贴更新的模板。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. 客户端应用程序还可以混合使用本机注册(不带模板的注册)和模板注册。Client applications can also mix native registrations (registrations with no template) and template registrations.

通知中心将针对每个注册发送一条通知,而不考虑这些注册是否属于同一客户端应用。The Notification Hub sends one notification for each template without considering whether they belong to the same client app. 可以使用此行为将与平台无关的通知转换成其他通知。This behavior can be used to translate platform-independent notifications into more notifications. 例如,可将发送到通知中心的同一条与平台无关的消息无缝地转换成 toast 警报和磁贴更新,而无需让后端知道这一情况。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. 如果在短时间内发送多个通知,某些平台(例如 iOS)可能会将这些通知合并发送到同一台设备。Some platforms (for example, iOS) might collapse multiple notifications to the same device if they are sent in a short period of time.

使用模板进行个性化设置Using templates for personalization

使用模板的另一个优点就是能够使用通知中心对通知执行基于注册的个性化设置。Another advantage to using templates is the ability to use Notification Hubs to perform per-registration personalization of notifications. 例如,假设某个天气应用需要显示一个磁贴,其中提供特定地点的天气情况。For example, consider a weather app that displays a tile with the weather conditions at a specific location. 用户可以选择摄氏度或华氏度,以及一天或五天的天气预报。A user can choose between Celsius or Fahrenheit degrees, and a single or five-day forecast. 使用模板,每个客户端应用安装可以注册所需的格式(1 天摄氏度、1 天华氏度、5 天摄氏度、5 天华氏度),并让后端发送一条消息,其中包含填充这些模板所需的全部信息(例如,使用摄氏度和华氏度的五天天气预报)。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).

使用摄氏温度的一天天气预报模板如下所示: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>

发送到通知中心的消息包含以下属性:The message sent to the Notification Hub contains all the following properties:

<table border="1">

<tr><td>day1_image</td><td>day2_image</td><td>day3_image</td><td>day4_image</td><td>day5_image</td></tr>

<tr><td>day1_tempC</td><td>day2_tempC</td><td>day3_tempC</td><td>day4_tempC</td><td>day5_tempC</td></tr>

<tr><td>day1_tempF</td><td>day2_tempF</td><td>day3_tempF</td><td>day4_tempF</td><td>day5_tempF</td></tr>
</table><br/>

通过使用此模式,后端只需发送一条消息,而不必为应用用户存储特定的个性化选项。By using this pattern, the backend only sends a single message without having to store specific personalization options for the app users. 下图演示了此方案:The following picture illustrates this scenario:

显示后端如何仅向每个平台发送一条消息的关系图。

如何注册模板How to register templates

若要使用安装模型(首选)或注册模型来注册模板,请参阅注册管理To register with templates using the Installation model (preferred), or the Registration model, see Registration Management.

模板表达式语言Template expression language

模板限定为 XML 或 JSON 文档格式。Templates are limited to XML or JSON document formats. 此外,只能在特定位置放置表达式;例如,对于 XML 放置节点属性或值,对于 JSON 放置字符串属性值。Also, you can only place expressions in particular places; for example, node attributes or values for XML, string property values for JSON.

下表显示了模板中允许使用的语言:The following table shows the language allowed in templates:

表达式Expression 说明Description
$(prop)$(prop) 对具有给定名称的事件属性的引用。Reference to an event property with the given name. 属性名称不区分大小写。Property names are not case-sensitive. 此表达式将解析为属性的文本值,如果该属性不存在,则解析为空字符串。This expression resolves into the property’s text value or into an empty string if the property is not present.
$(prop, n)$(prop, n) 同上,但会在 n 个字符处对文本进行显式剪切,例如,$(title, 20) 会在 20 个字符处对 title 属性的内容进行剪切。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) 同上,但会在剪切后的文本后面添加三个点作为后缀。As above, but the text is suffixed with three dots as it is clipped. 剪切后的字符串以及后缀的总大小不超过 n 个字符。The total size of the clipped string and the suffix does not exceed n characters. 对输入属性“This is the title line”使用 .(title, 20) 会生成 This is the title....(title, 20) with an input property of “This is the title line” results in This is the title...
%(prop)%(prop) 类似于 $(name),不过其输出已经过 URI 编码。Similar to $(name) except that the output is URI-encoded.
#(prop)#(prop) 在 JSON 模板中使用(例如,用于 iOS 和 Android 模板)。Used in JSON templates (for example, for iOS and Android templates).

此函数的工作方式与前面指定的 $(prop) 完全相同,但在 JSON 模板(例如 Apple 模板)中使用时例外。This function works exactly the same as $(prop) previously specified, except when used in JSON templates (for example, Apple templates). 在此示例中,如果此函数未由“{”、“}”括起来(例如,‘myJsonProperty’ : ‘#(name)’),并按 Javascript 格式(例如,regexp: (0|([1-9][0-9]*))(.[0-9]+)?((e|E)(+|-)?[0-9]+)?)求出一个数字值,则输出 JSON 是一个数字。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.

例如,‘badge: ‘#(name)’ 将变为 ‘badge’ : 40(而不是 ‘40‘)。For example, ‘badge: ‘#(name)’ becomes ‘badge’ : 40 (and not ‘40‘).
‘text’ 或 “text”‘text’ or “text” 一个文本。A literal. 文本包含以单引号或双引号括住的任意文本。Literals contain arbitrary text enclosed in single or double quotes.
expr1 + expr2expr1 + expr2 用于将两个表达式联接成单个字符串的串联运算符。The concatenation operator joining two expressions into a single string.

表达式可以采用上述任一格式。The expressions can be any of the preceding forms.

使用连接时,必须使用 {} 括住整个表达式。When using concatenation, the entire expression must be surrounded with {}. 例如,{$(prop) + ‘ - ’ + $(prop2)}For example, {$(prop) + ‘ - ’ + $(prop2)}.

例如,以下模板不是有效的 XML 模板:For example, the following template is not a valid XML template:

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

如前所述,使用串联时,表达式必须用大括号括住。As explained earlier, when using concatenation, expressions must be wrapped in curly brackets. 例如:For example:

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

后续步骤Next steps

了解 Azure 通知中心Learn about Azure Notification Hubs