Screen branding guide

Rogerthat makes it possible to include your logo, brand, or company style in the messages you sent to users. This concept is called
screen branding.

The following screens can be branded:

  • Service-to-person messages and forms
  • Service home screen menu
  • Service desciption page
    • Note: this page is also shown when a user pokes your service while he is not yet connected to your
      service)
  • Static content behind homescreen icons

Check the following message, once with and once without branding.

iPhone branded message

iPhone non-branded message

Android branded message

Android non-branded message

Overview

Branding impacts how screens are visualized on the mobile devices or in the browser of Rogerthat recipients.

  • A branding archive is packaged as a single zip file, as explained below.
  • A branding archive contains an HTML-based look and feel. The message content, timestamp and other items are
    inserted in the branding when it is visualized.
  • One or more branding archives can be uploaded upfront in the Service Panel. Every branding gets a unique
    branding identifier.
  • You can select which branding to use for messages. In the message flow designer, this is a simple dropdown. In
    the API, you have to set the branding property. In
    this field you put the branding identifier.
  • Home screen branding and description branding can be set in the service panels.
  • You can create your branding by uploading it in the service panels, or by using the API system.store_branding.

Branding Archive Structure

Branding Archive Content

The toplevel folder of a branding archive must contain the file
branding.html and optionally a few images and style sheets to spice up the look and feel. The total branding archive cannot be larger than 200K. It is not possible to create subdirectories in a branding archive.

The branding files will be parsed by the Rogerthat software. When rendered, the following HTML tags are replaced:

  • <span><nuntiuz_message/></span> will be replaced by the message text. Newlines inside
    the message text will be replaced with <br> This is only useful for messages and forms.
  • <span><nuntiuz_timestamp/></span> will be replaced by the message timestamp.This is
    only useful for messages and forms.
  • <span><nuntiuz_identity_name/></span> will be replaced by the name of the service. This
    is useful for messages, forms, static content, home screen menu branding and service description branding.

You can include links in your branding. This is useful when using them as static HTML content behind one of your service home screen buttons:

  • <a href=”mailto:email@example.com”>Send email</a> will open the email app. You can define
    recipients, subject, message body all in one URL. For more information check wikipedia.
  • <a href=”tel:+123456789″>Call us</a> will dial a phone number.
  • <a href=”nuntiuz_poke_tag://my_poke_tag”>Start an action</a> is a special href
    directive which will render a button on the HTML page when viewed in Rogerthat. When pressed, the system will
    “poke” your service with the tag that was included in the href. In this case, the tag is my_poke_tag –
    this way you can automatically start a message flow from a static content page.
  • Note: links to another website using HTTP(S) are currently not supported

Additional configuration of the look and feel is possible using meta tags in branding.html:

  • <meta property=”rt:style:background-color” content=”#ffffff”/> will set the background color of the
    full screen around the message body (except for navigation bars)
  • <meta property=”rt:style:show-header” content=”true”/> allows you to hide the header when a message
    is displayed. This way, the service logo, name and email address can be hidden. You should include
    identification of the sender in your branding.
  • <meta property=”rt:style:color-scheme” content=”dark”/> will set the color scheme of the header.
    When you have a dark background (e.g. black) you should use colorscheme dark. For a light background use
    light. This way, the text in the header is readable for the user.
  • <meta property=”rt:style:orientation” content=”portrait”/> defines the supported orientations of
    the branding.
    The possible values are

    • portrait: The branding can only be watched in portrait mode. This is the default value.
    • landscape: The branding can only be watched in landscape mode.
    • dynamic: The branding can be watched in both portrait and landscape mode.
  • <meta property=”rt:style:display-type” content=”native” /> Will set the display type of the branding.
    The possible values are:

    • native: Renders the branding natively, using specific files in the branding (avatar.jpg and
      logo.jpg).
      This is the preferred method, but is only supported as of november 2016. Older clients will use the
      ‘webview’ display type.
    • webview: Renders the branding in a webview, giving you more customizable at the cost of loading
      speed.

Restrictions

Do not create directories inside the branding archive.

The parser will validate some restrictions on the branding files

  • HTML templates must be encoded in UTF-8
  • The HTML <head> section must contain the following tag
    <meta http-equiv=”Content-Type”
    content=”text/html; charset=utf-8″/>
  • The HTML MUST NOT include or refer to other files from remote locations. ALL includes (CSS & images) must be
    packaged in the branding archive.
  • The HTML MUST NOT contain links to remote websites.
  • The following HTML tags are prohibited:
    • <applet>
    • <object>
    • <script>

Branding HTML

We will create the branding.html file for a fictitious Car Repair service. Apart from the two HTML files, we included a single image
car_128.png in the branding.

Important parts in the branding files are highlighted:

  • Content-Type must be set to UTF-8
  • nuntiuz_message placeholder
  • nuntiuz_timestamp placeholder

Scroll to the bottom of this page to see the example file content for branding.html

Now we create the branding archive:

Carl-DHalluins-MacBook-Pro-2:branding carl$ ls -l
total 48
-rwxr-xr-x@ 1 carl  wheel   1109 Sep 26 14:40 branding.html
-rw-r--r--@ 1 carl  staff  12609 Sep 26 09:11 car_128.png


Carl-DHalluins-MacBook-Pro-2:branding carl$ zip ../branding.zip *
updating: branding.html (deflated 53%)
updating: car_128.png (deflated 0%)

Next, go to the Service Control
Panel and upload the branding archive:

Click the Preview button to check how your message will be visualized on a mobile phone:

You might want to modify your branding a couple of times, and check the preview each time. Once you are happy with the look and feel, you can start sending some real messages:

  • The branding identifier is shown in the service control panel. In the example, the branding identifier is CC01398A6F61F73BDC6EFC54C5BA9C5CA01907EF8752E5DDB798ADD6F8504B82
  • You can send a branded message by setting the branding field in the messaging.send API call: 
            POST /api/1/ HTTP/1.1
        Content-type: application/json-rpc
        X-Nuntiuz-API-Key: your_secret_api_key

        {
        "method": "messaging.send",
        "params": {
        "parent_message_key": null,
        "message": "This is a test message",
        "answers": [ ],
        "sender_answer": null,
        "flags": 31,
        "alert_flags": 1,
        "members": [
        "john@example.com"
        ],
        "branding": "CC01398A6F61F73BDC6EFC54C5BA9C5CA01907EF8752E5DDB798ADD6F8504B82",
        "tag": "37AAF801-CE21-4AC5-9F43-E8E403E1EB5F"
        },
        "id": "CB9FBCB4-E099-43CA-810A-632A1CF60869"
        }

Example branding.html

<html>
<!-- branding.html example -->

<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <meta property="rt:style:background-color" content="#ffffff"/>
    <meta property="rt:style:show-header" content="true"/>
    <meta property="rt:style:color-scheme" content="light"/>
    <style type="text/css">
        body { background: #ffffff;
            font-family: Arial; color: #333333;
            font-family: Arial !important;
            font-size: 1em; }

        #info { color: #00A8FF;
            font-size: 1.2em;
            font-weight: bold;
            text-align: right; }

        #title { float: left;
            color: #000000;
            font-size: 1.2em;
            font-weight: bold; }

        #footer { color: #777777;
            font-size: 0.8em;
            font-style: italic; }
    </style>
</head>

<body>

<div style="float:left;">
    <img src="car_128.png"/>
</div>

<div id="info">
    Tom's Car Repair<br>
    23, High Street<br>
    My Home Town<br><br>
    +1 232 552 4152
</div>

<div style="clear:both;"/>

<div id="title">Appointment reminder</div>

<div style="clear:both;"></div>

<br><span><nuntiuz_message/></span><br><br>

<div id="footer">This message was sent at <span><nuntiuz_timestamp/></span>.</div>

</body>

</html>

Uploading a screen branding

The method described above shows you how to create a screen branding archive file, and how to upload it to the Rogerthat cloud in the service panels.

An alternative method is to programmatically upload a branding archive using the API call
system.store_branding – for more information refer to the API Reference