Developer Reference. A mobile loyalty platform for retailers. Document Number:

(1)

Developer Reference

A mobile loyalty platform for retailers

(2)

(3)

C

ONTENTS

Guide Overview Description of this Guide ... ix

What’s new in this guide ...x

Upgrade impact ... xii

1. Getting Started with Alert Introduction... 1

Overview of the Alert platform ... 1

Creating an e-commerce platform for your customers ... 3

Creating an Alert-based mobile app ... 3

Integrating your product catalog ... 4

Integrating your organization’s infrastructure: the Alert APIs... 5

Creating a loyalty program for your customers: Alert Loyalty ... 6

Rewarding customers for activities on social networks: Social Loyalty... 7

Rewarding customers for purchases in your stores: Purchase-based Loyalty ... 8 2. Customizing an Alert App Introduction... 11 Customization overview... 12 Common customizations... 13

Prerequisites for customizing your app... 13

High-level steps for customizing your app ... 14

The Alert skin bundle ... 15

Structure of an iOS skin bundle ... 15

Structure of an Android skin bundle... 16

Customizing the images in the app... 17

(4)

Images used for branding ... 19

Images used for content elements... 21

Images used for navigation elements in iOS ... 24

Images used for navigation elements in Android... 25

Images used for navigation menu icons in iOS... 26

Customizing the colors used in the app... 28

Steps to customize the colors used in the app ... 28

JSON name/value pairs for colors ... 29

Customizing the app’s navigation menu ... 33

Structure of the navigation menu ... 34

Customizing the order of items in the app’s navigation menu... 37

Adding new items to the navigation menu in iOS ... 40

Adding new items to the navigation menu in Android ... 41

Customizing the app’s Explore page ... 43

Customizing the app’s Inbox page... 45

Customizing the app’s Account page ... 48

Structure of the Account page ... 49

Customizing the order of items in the Account page ... 51

Adding new items to the Account page in iOS... 53

Adding new items to the Account page in Android ... 54

Customizing the account creation parameters ... 56

Steps to customize the account creation parameters ... 56

JSON name/value pairs for account creation ... 57

Customizing the app’s Social page... 59

Structure of the Social page ... 60

Customizing the order of items in the Social page... 61

Adding new tabs to the Social page in iOS... 63

Adding new tabs to the Social page in Android ... 64

Customizing the text in the app in iOS... 65

Steps to customize the text in the app in iOS ... 66

Navigation menu text that you can customize ... 67

Loyalty card text that you can customize... 68

Gift card text that you can customize... 68

Notification text that you can customize... 69

Login request text that you can customize... 70

“No content” text that you can customize... 70

Account page text that you can customize ... 71

Customizing the text in the app in Android ... 71

(5)

Loyalty card text that you can customize... 74

Gift card text that you can customize... 75

Notification text that you can customize... 75

“No content” text that you can customize... 76

Login request text that you can customize... 76

Customizing the text sent from the app in iOS ... 77

Steps to customize the text sent from the app in iOS ... 77

Messages that you can customize in iOS ... 78

Posts for social networks from iOS ... 80

Customizing the text sent from the app in Android ... 81

Steps to customize the text sent from the app in Android... 82

Messages that you can customize in Android... 83

Customizing email messages sent from the app ... 84

Downloading the email templates ... 84

Steps to customize the email messages sent from the app... 85

Common iOS customizations for email messages ... 87

Automatically customizable text: Macros... 89

List of user account and app download macros... 90

List of product offer macros ... 90

List of Inbox macros... 91

List of gift macros... 91

List of shared product macros... 92

List of receipt macros... 92

Adding a link to the app’s Account page... 92

Compiling your customized skin ... 95

Testing the customized skin for iOS ... 96

Testing a custom splash screen ... 97

Making your custom Alert-based app available ... 98

Allowing MicroStrategy to distribute your app... 98

Deploying your iOS app on the Apple App Store... 99

Deploying your Android app on the Google Play store... 100

3. The Alert Administration API Introduction... 103

Prerequisites for using the Alert API... 104

Using the Alert API: Creating Alert administration sessions ... 105

Obtaining an Alert administration session token... 105

Creating and managing your store locations: Store Location API ... 107

Creating a store location... 108

(6)

Updating a store location ... 116

Deleting a store location ... 119

Retrieving store locations... 120

Connecting your customer database to Alert accounts: Customer Linking API ... 121

Linking a customer’s account to their Alert user ID... 122

Un-linking a customer’s account and their Alert user ID ... 124

Sending offers to customers: Offers API ... 126

Obtaining Alert user IDs for targeted offers ... 126

Adding customers to a message... 128

Deleting customers from a message’s recipient list... 133

Sending coupon codes to customers... 136

Deleting coupon codes from customers’ accounts ... 141

Retrieving unclaimed coupon codes that have been assigned to customers ... 144

Redeeming coupons... 146

Creating and managing receipts: Receipts API ... 148

Creating receipts... 149

Deleting receipts ... 167

Replacing receipts (deprecated) ... 169

Retrieving receipts ... 172

Managing your purchase-based loyalty program... 177

Retrieving a customer’s loyalty points... 178

Retrieving a customer’s loyalty activities ... 181

Redeeming a customer’s loyalty points ... 185

Tracking your social loyalty programs ... 187

Retrieving a list of social loyalty activities ... 188

Redeeming customers’ social loyalty points ... 193

Integrating users’ information with your infrastructure: External Alert sessions ... 196

Retrieving the contents of users’ wallets... 196

Adding gift cards to users’ wallets... 200

Retrieving users’ account information... 201

4. The Alert Partner API Introduction... 205

Getting started with the Partner API ... 206

Implementing the Partner API... 207

Managing customers’ authentication accounts using the Partner API ... 209

(7)

accounts ... 225

Authenticating customers ... 232

Retrieving customers’ account information ... 240

Updating customers’ account information... 245

Resetting customers’ passwords ... 255

Merging Alert accounts ... 259

Managing customers’ loyalty information using the Partner API ... 264

Creating new loyalty memberships for customers ... 265

Retrieving customers’ membership information... 270

Linking customers’ loyalty memberships to their Alert accounts ... 273

Un-linking a customer’s membership... 277

Retrieving additional information from customers... 279

Requesting additional customer information using an external Alert session ... 280

Customizing your Alert app to retrieve user information ... 281

Using the Partner API for customers’ gift cards... 286

Allowing Alert to check the balance on a gift card ... 286

5. Integrating your Magento Store with Alert Introduction... 289

Installing and configuring the Alert Connector for Magento... 290

Installing the Alert Magento Extension... 292

Using Magento with your Alert-based App ... 294

Displaying product options as images ... 297

(8)

(9)

G

UIDE

O

VERVIEW

Description of this Guide

This guide describes the tasks you can perform to create a custom mobile commerce application for your customers.

This guide is divided into the following sections:

• For an overview of the Alert platform, see Chapter 1, Getting Started with Alert.

• If you want to create a custom Alert-based app that uses your organizations’ branding, see Chapter 2, Customizing an Alert App.

• If you are creating a web application to administer your Alert Campaign Management System (CMS) store, for example, to update your physical store locations, you can use the Alert Administration API, described in Chapter 3, The Alert Administration API.

(10)

• If you use the Magento e-commerce platform to manage your product catalog, you can use the Alert Magento Connector to provide an integrated native shopping experience to users of your Alert app. For instructions to install and configure the Magento Connector, see Chapter 5, Integrating your Magento Store with Alert.

What’s new in this guide

Alert 3.7

• If you use the Magento e-commerce platform to manage your product catalog, you can use the Alert Magento Connector to provide an integrated native shopping experience to users of your Alert app. For instructions to install and configure the Magento Connector, see Chapter 5, Integrating your Magento Store with Alert.

Alert 3.6

• You can use the Alert Loyalty Program as a purchase-based loyalty solution for your customers. For an overview of the Alert Loyalty Program, see Creating a loyalty program for your customers: Alert Loyalty, page 6.

For the APIs that you can use to manage your purchase-based loyalty program, see Managing your purchase-based loyalty program, page 177.

• The Receipts API has been updated to support purchased-based loyalty programs. For detailed information on the Receipts API, see Creating and managing receipts: Receipts API, page 148.

If you are using an older version of the Receipts API, the API calls remain backward compatible.

• The API to replace receipts has been deprecated.

• You can send messages to your customers using the Offers API, described in Adding customers to a message, page 128.

(11)

• Additional customization options are available for the customizable Alert app:

In the navigation menu, you can specify the background color of each navigation icon using the icon_bg_color key, as described in Structure of the navigation menu, page 34.

The navigation menu now supports additional controllers, as listed in Controller IDs used in app links, page 35.

The items on the user’s Account Page can be customized, as described in Customizing the app’s Account page, page 48.

The tabs on the Social page can be customized, as described in Customizing the app’s Social page, page 59.

Alert 3.5

• If you have integrated your customers’ authentication accounts or loyalty memberships with the Alert platform, you can use the authentication account IDs or loyalty membership IDs while making requests to the Alert Administration API, or handling requests for the Alert Partner API. For details on the request formats for the Alert Administration API, see Chapter 3, The Alert Administration API. For details on the request formats for the Alert Partner API, see Chapter 4, The Alert Partner API.

• If you have created a social loyalty program for your customers, for example, one that awards loyalty points for sharing a product with their contacts, you can track the activities for users who have participated in the program. The API calls for tracking social loyalty activities are described in Tracking your social loyalty programs, page 187.

• If you are implementing the Alert Partner API, it is recommended that you test your API implementation. The guidelines for testing are provided in Testing your Partner API implementation, page 209.

Alert 3.0

(12)

Upgrade impact

The sections below describe new or changed features for the latest version of the Alert platform, and the impact of the changes on your Alert API

implementations.

Upgrading to Alert 3.6

• The API call to replace receipts has been deprecated.

To replace a receipt, you must first delete the old receipt using the API call described in Deleting receipts, page 167, and create a new receipt using the API call described in Creating receipts, page 149.

(13)

1

1.

G

ETTING

S

TARTED

WITH

A

LERT

Introduction

This section provides an overview of the Alert platform, and describes the high-level steps to integrate your organization’s customer database. The following topics are covered:

• For an overview of the Alert platform and the features it offers, see Overview of the Alert platform, page 1.

• For high-level steps to integrate your customer database with Alert, see Creating an e-commerce platform for your customers, page 3.

• For high-level steps to use Alert as a loyalty program for your customers, see Creating a loyalty program for your customers: Alert Loyalty, page 6.

Overview of the Alert platform

(14)

customer systems, such as Customer Relationship Management (CRM) databases, point-of-sale (POS) systems, loyalty programs, and so on, as well as your marketing assets to deliver a tightly integrated user experience on your customers’ iOS and Android devices.

Features of the Alert platform

The Alert platform offers you and your customers the following abilities:

• You can send targeted offers to your customers through the Alert

Campaign Management System (CMS). Customers can use these offers in your store locations, or gift them to their contacts.

• You can use Alert as a customer loyalty platform, rewarding customers for purchases they make in your stores, or for sharing your products and updates with their contacts.

• If you have an existing loyalty program, you can integrate Alert with your program and offer your customers loyalty badges that they can use in the Alert apps for web and mobile.

• You can analyze your customers’ behavior and profiles using Alert CMS, and create customer segments based on your analyses.

• You can send your customers receipts for purchases that they have made at your stores.

• You can integrate your own mobile commerce site with the Alert apps, allowing your customers to make purchases from within the app.

• You can send users coupons and loyalty badges, which can be scanned at your store locations.

• You can create public offers, which potential customers can browse without logging in to the app. When they are ready to make a purchase, they can log in to the app.

• Your customers can use the Store Locator feature in the Alert app to find your stores in their vicinity.

• You can integrate your product catalog with the Product Locator feature, so that customers can find products that they are looking for.

(15)

Creating an e-commerce platform for your

customers

You can use the Alert platform to create an integrated mobile commerce experience for your customers, which incorporates your branding, product catalog, and your existing customer data.

The high-level tasks you can perform to create a mobile commerce platform with Alert are as follows:

• Create a custom, Alert-based mobile app, which uses your organization’s branding, as described in Creating an Alert-based mobile app, page 3.

• Allow customers to browse your product catalog and make purchases from within your Alert-based app, by adding your mobile store to your the app, as described in Integrating your product catalog, page 4.

• Allow your customers to sign up for your loyalty programs, or add their current loyalty memberships to the Alert platform, as described in Integrating your organization’s infrastructure: the Alert APIs, page 5.

Creating an Alert-based mobile app

The Alert platform provides a demo app, called Trela, which can be

(16)

You can create a custom skin for the Trela app, using your company’s logo, text, color scheme, and images. MicroStrategy then uses that skin to create a version of the app tailored to your needs. If required, you can make your app accessible to an international audience by providing MicroStrategy with translations for the text used in the app.

The basic requirements for creating a skin for the Trela app are as follows:

• A basic understanding of the JavaScript Object Notation (JSON) format.

• A text editor.

• An image editor.

For detailed requirements, and instructions to create your Alert-based app, refer to Chapter 2, Customizing an Alert App.

Integrating your product catalog

You can allow Alert users to browse your product catalog and purchase goods from you from within the Alert app, using one of these strategies:

• If you use the Magento e-commerce platform to manage your products, you can use the Alert Connector for Magento to integrate your Magento store with your Alert-based app. The Alert Connector allows customers to interact with your app in the same way that they interact with your Magento store, while taking advantage of Alert’s features to provide a native shopping experience optimized for mobile devices.

For steps to install and configure the Alert Connector for Magento, see Chapter 5, Integrating your Magento Store with Alert.

(17)

Search for products by scanning a barcode, as shown in the example below:

For detailed steps to integrate your mobile store in your Alert-based app, refer to the Alert CMS help, located at http://www2.microstrategy.com/ producthelp/AlertCMS/Help/index.html.

(18)

The following are examples of capabilities that you can offer your customers using the Alert APIs:

• When customers make purchases at your stores, your point-of-sale (POS) system can send them electronic receipts, which can be viewed in your Alert-based app.

• When customers claim coupons for campaigns that you have created, you can send them coupon codes that they can access in the Alert-based app.

• If you have created loyalty programs for your customers, you can track these programs, and update customers’ accounts with the loyalty points they earn.

There are two sets of APIs that you can use, described as follows:

• The Alert Administration API, which allows you to administer your Alert store. To use the Administration API, you create a web service that calls the API to perform tasks such as managing your store locations, sending receipts to your customers, and so on.

The Administration API is described in detail in Chapter 3, The Alert Administration API.

• The Alert Partner API, which allows you to integrate your customer database with Alert. The Partner API must be implemented in a web service that you create, and responds to calls from the Alert platform. The Partner API is described in detail in Chapter 4, The Alert Partner API.

Creating a loyalty program for your customers:

Alert Loyalty

The Alert Loyalty program lets you reward your customers for their

interactions with your brand, for example, by awarding customers 10 loyalty points every time they spend $100 in one of your stores.

The Alert Loyalty program helps you achieve the following:

• Engage your customer base with rewards for social actions, online purchases, and purchases in your store locations.

(19)

• If you have your own loyalty program, integrate your loyalty program with Alert.

• Track the success of your loyalty programs, and view reports on loyalty activities using Alert Intelligence.

• Define market segments based on customers’ loyalty data, and create campaigns specifically targeting customers who have loyalty

memberships with you.

The Alert Loyalty program offers the following solutions:

• Rewarding customers for activities on social networks: Social Loyalty, page 7

• Rewarding customers for purchases in your stores: Purchase-based Loyalty, page 8

Rewarding customers for activities on social networks: Social

Loyalty

A social loyalty program lets you reward your customers for sharing your offers and updates with their contacts using Facebook, email, or SMS text message.

The high-level tasks for implementing a social loyalty program are as follows:

• In the Alert Campaign Management System (CMS), you define the actions that allow users to earn loyalty points. For example:

Sharing one of your offers with their Facebook contacts. Liking your Facebook posts.

Sharing your Facebook posts.

• If you do not have your own loyalty program, Alert manages your customers’ loyalty information.

• If you have your own loyalty program, you can use the Alert APIs to retrieve your customers’ activities in Alert, and add them to your loyalty program.

For steps to create social loyalty programs in CMS, refer to the Alert CMS

(20)

Rewarding customers for purchases in your stores:

Purchase-based Loyalty

The Alert Loyalty Program allows you to support an end-to-end purchase-based loyalty solution. The purchase-based loyalty platform includes:

• A loyalty platform, hosted within Alert.

• APIs in the Alert platform, which let you:

Send Alert receipts for customers’ purchases, indicating the loyalty. Retrieve customers’ loyalty points and activities, to display on your website.

Update customers’ loyalty accounts when they redeem their loyalty points at one of your stores.

You can create a purchase-based loyalty program for all customers who have a loyalty membership with you. The high-level workflow for a

purchase-based loyalty program is as follows:

1 In CMS, you create a purchase-based loyalty program, and configure the following options:

• The relationship between purchase amounts and the loyalty points awarded to customers. For example, you can define a rule that for each $10 customers spend, they get 1 loyalty point.

• The period for which customers’ loyalty points are marked as pending. Typically, this period matches your product return policy, and ensures that customers can only use their loyalty points once the purchase is final.

Once the period has concluded, the loyalty points are added to the customer’s points balance.

For social loyalty programs, the points that customers earn are added to their loyalty points balance immediately.

2 In your Alert-based app, your customers sign up for your loyalty program.

(21)

4 Your point-of-sale (POS) terminal sends Alert the receipt for the

purchase using the Receipts API, and indicates the purchase amount that is eligible for loyalty points. For example, if a customer's purchase totals $100, of which $50 is eligible for your loyalty program, the receipt indicates that $50 is the amount eligible for calculating loyalty points. Customers can view their receipts in your Alert-based app, or through your website.

You can send receipts to Alert for the following customers:

• Customers who track their loyalty memberships using your Alert-based app.

• Customers who track their loyalty memberships through your website.

The API calls for the Receipts API is described in Creating and managing receipts: Receipts API, page 148.

5 Based on the rules you define in CMS, the Alert platform calculates the number of points and adds it to the customer’s pending loyalty points.

6 If customers return items, your POS terminal creates a receipt for the return using the transaction ID for the original receipt. The receipt for the returned items indicates the amount that is to be deducted from the original purchase, as well as the amount for loyalty points to deduct.

7 When your customers log on to your website to track their loyalty

information, you use Alert API calls to retrieve the following information about the customer’s activities:

• Their current points balance, including their pending points. The API call to retrieve a customer’s loyalty points is described in Retrieving a customer’s loyalty points, page 178.

• Their activity history. The API call to retrieve a customer’s loyalty activities is described in Retrieving a customer’s loyalty activities, page 181.

(22)

(23)

2

2.

C

USTOMIZING

AN

A

LERT

A

PP

Introduction

The MicroStrategy Alert mobile app can be easily customized for your use. You can create a custom skin for the mobile app using your company’s logo, text, and images. MicroStrategy then uses that skin to create a version of the app tailored to your needs. If required, you can make your app accessible to an international audience by providing MicroStrategy with translations for the text used in the app.

For more information about any aspect of customizing the Alert app, including instructions, select from the following:

• Customization overview, page 12

• Customizing the images in the app, page 17

• Customizing the colors used in the app, page 28

• Customizing the app’s navigation menu, page 33

• Customizing the app’s Account page, page 48

(24)

• Customizing the app’s Social page, page 59

• Customizing the text in the app in iOS, page 65

• Customizing the text in the app in Android, page 71

• Customizing the text sent from the app in iOS, page 77

• Customizing the text sent from the app in Android, page 81

• Customizing email messages sent from the app, page 84

• Automatically customizable text: Macros, page 89

• Adding a link to the app’s Account page, page 92

• Compiling your customized skin, page 95

• Testing the customized skin for iOS, page 96

• Making your custom Alert-based app available, page 98

Customization overview

To customize your Alert app, you change the text and images used in the app skin. You can download a sample skin from MicroStrategy, which contains all the images and text, and make your changes. Then you send the skin to MicroStrategy to create your app.

For example, a retailer can use Alert to create a custom storefront app. Customers who have downloaded the app receive messages about sales and special items, tailored to their demographic information. While they are in the store, they can use their smartphone camera as a QR code scanner to retrieve information about items.

For an overview of specific aspects of customizing your app, see the following:

• Common customizations, page 13

• Prerequisites for customizing your app, page 13

• High-level steps for customizing your app, page 14

(25)

Common customizations

Some common customizations that are made to the Alert app include:

• Changing the splash screen to an image specific to your company (see Customizing the images in the app, page 17)

• Changing the color scheme and icons to reflect your company’s brand (see Customizing the colors used in the app, page 28 and Customizing the images in the app, page 17)

• Changing the notification text so that it is specific to your app (see Customizing the text sent from the app in iOS, page 77 or Customizing the text sent from the app in Android, page 81)

• Customizing the items in the navigation menu so that they reflect your use cases (see Customizing the app’s navigation menu, page 33)

• Changing the email messages that users send from the app so that they link to your company’s products (see Customizing email messages sent from the app, page 84)

Prerequisites for customizing your app

• You must have access to an iOS or Android device that can install the Trela demo app.

• You should have a basic understanding of HTML and JavaScript Object Notation (JSON) files. For an introduction to the JSON file format, see the W3Schools introduction to JSON, at

http://www.w3schools.com/json/json_intro.asp.

• You must have access to a text editor that can save text files in UTF-8 encoding.

• To customize the images in the app, you must have access to an image editor that can create .PNG files.

• To customize the colors in the app, you must have a basic understanding of how to define colors as hexadecimal values.

(26)

High-level steps for customizing your app

The general workflow for customizing your Alert-based app is as follows:

1 Download the Trela demo app from the appropriate location for your mobile device:

• For iOS devices: Download Trela from the Apple App Store

• For Android devices: Download Trela from Google Play

2 Explore the Trela app to identify the images, colors, or text that you want to customize.

3 Download a sample skin from the MicroStrategy support website. For information about the sample skin, including a download location, see The Alert skin bundle, page 15.

4 In the sample skin, add the images that you want to customize. For example, you may want to use your company’s logo in the splash screen. For steps to customize images, see Customizing the images in the app, page 17.

5 Review and customize the colors that you want to edit. For example, you may want to change the colors of the app’s navigation bars. For steps to customize colors, see Customizing the colors used in the app, page 28.

6 Review and customize the app’s navigation menu, Account page, and Social page. For example, you may want to change the default name of the Loyalty Cards section to a term that fits with your branding. For steps to customize these screens, see Customizing the app’s navigation menu, page 33, Customizing the app’s Account page, page 48, Customizing the account creation parameters, page 56, and Customizing the app’s Social page, page 59.

7 Review and customize the text in the app that you want to edit. For example, you may want to change the text that is displayed for the Loyalty Cards section. For steps to customize text, see Customizing the text in the app in iOS, page 65, Customizing the text sent from the app in iOS, page 77, and Adding a link to the app’s Account page, page 92.

(27)

9 Compile your modified version of the template skin. For steps to compile the skin, see Compiling your customized skin, page 95.

10 If you are using an iOS app, install your custom skin on a device and test it. For steps to test the skin, see Testing the customized skin for iOS, page 96.

11 Deliver the compiled skin to MicroStrategy. A MicroStrategy team creates a custom app using the skin you have customized.

12 Make your custom app available to your customers. For high-level steps to make your app available on the appropriate app store, see Making your custom Alert-based app available, page 98.

The Alert skin bundle

You can download an Alert skin from the MicroStrategy website, from one of the following locations:

• For iOS devices, the skin can be downloaded from

http://www2.microstrategy.com/producthelp/AlertDeveloper/Skin/iO STrelaSkin.zip

• For Android devices, the skin can be downloaded from

http://www2.microstrategy.com/producthelp/AlertDeveloper/Skin/A ndroidTrelaSkin.zip

An Alert skin is a compressed ZIP archive, containing a skin.bundle folder. The structure of the folder is different depending on the device.

• For iOS devices, see Structure of an iOS skin bundle, page 15.

• For Android devices, see Structure of an Android skin bundle, page 16.

Structure of an iOS skin bundle

• The iOS skin.bundle file can be downloaded from

(28)

It contains the following items, as shown in the image below:

• en.lproj folder: Contains files with localization information.

Localizable.strings file: Contains all the text used in the app. You can edit this file to change the text used in the app, or to translate the text into different languages.

• Resources folder: Contains additional files used by the skin. Images folder: Contains all the images used by the skin.

• skin.json file: Contains text that you can customize for the iPhone, such as items in the app’s navigation menu, and the colors that are used in the interface.

• skin-ipad.json file: Contains text that you can customize for the iPad, such as items in the app’s navigation menu, and the colors that are used in the interface.

• text_templates.json file: Contains the messages that are sent to other users from the app, for example, when sharing an offer via email. For the structure of an Android skin bundle, see Structure of an Android skin bundle, page 16.

Structure of an Android skin bundle

The Android skin.bundle file can be downloaded from

(29)

• Resources folder: Contains additional files used by the skin. Images folder: Contains all the images used by the skin.

• skin.json file: Contains text that you can customize, such as items in the app’s navigation menu, and the colors that are used in the interface.

• strings.xml file: Contains all the text used in the app. You can edit this file to change the text used in the app, or to translate the text into

different languages. To, download a sample strings.xml, click the following URL:

http://www2.microstrategy.com/producthelp/AlertDeveloper/Skin/A ndroid_strings_sample.xml.

For the structure of an iOS skin bundle, see Structure of an iOS skin bundle, page 15.

Customizing the images in the app

You can customize the images used in the Alert app. For example, you can change the splash screen and login page so that they display your company’s logo, or use customized menu buttons.

For detailed instructions on how to customize the images in the skin, see Steps to customize the images in the skin, page 18.

For specific images to customize, see the following:

• For images that represent your brand, see Images used for branding, page 19.

• For images used for items, see Images used for content elements, page 21.

(30)

On Android, see Images used for navigation elements in Android, page 25.

• For images used for navigation menu icons, on iOS, see Images used for navigation menu icons in iOS, page 26.

Steps to customize the images in the skin

The images used in your skin are contained in the \Images folder of

skin.bundle. By default, the Images subfolder is empty, and the skin uses the app’s built-in images.

To download an archive containing all the images used in the app, select from the following links:

• For iOS: http://www2.microstrategy.com/producthelp/AlertDeveloper/S kin/iOSAlertImages.zip • For Android: http://www2.microstrategy.com/producthelp/AlertDeveloper/S kin/AndroidAlertImages.zip Prerequisite

To customize the images in your app, you need an image editor that can save images at a specified pixel size, in PNG format, with various properties such as transparency as specified for each image.

To customize an image in the skin

1 Browse through the demo app, and use the following sections to identify the image in the app that you want to customize:

• For images that represent your brand, see Images used for branding, page 19.

• For images used for items, see Images used for content elements, page 21.

(31)

• For images used for navigation menu icons, on iOS, see Images used for navigation menu icons in iOS, page 26.

2 Create a new image, in PNG format, with the specified height, width, and any additional properties.

If you are developing an iOS skin, then to take advantage of

high-resolution screens on newer devices, MicroStrategy recommends that you create multiple versions of each image, described as follows:

• A standard-resolution image which is displayed on devices with low-resolution screens, such as older-generation iPhone devices.

• A high-resolution image that is double the size of the

standard-resolution image, to take advantage of high-resolution screens on some devices, such as the iPhone 4 and 4s. The file name of the high-resolution image is the same as the standard-resolution image, with an @2x suffix. For example, if the standard-resolution image is example.png, the high-resolution image is

[email protected].

• For some full-screen images, you must create an extended

high-resolution version of the image to take advantage of the larger screen size of devices such as the iPhone 5. The file name of the extended high-resolution version of the image is the same as the standard-resolution image, with an -568h@2x suffix. For example, if the standard-resolution image is example.png, the high-resolution image is [email protected].

3 Save your images in the \Images folder of the sample skin, using the file name specified for the image. For any images that you do not customize, the default image is used.

Images used for branding

(32)

For steps to customize these images, see Steps to customize the images in the skin, page 18.

Description Image to customize Specifications (height x width, _{in pixels)}

A large version of the app’s logo, displayed on the login page for the app.

iOS:

logo_trela_splash.png Android:

trela_logo.png

iOS standard resolution: 215 x 175 px

iOS high resolution (@2x suffix): 430 x 170 px

Android: 460 x 110 px

Note: The image background

must be set to alpha transparent.

The splash screen that is displayed when the app starts. This image should not contain the logo, as the logo is displayed with the login and connect buttons (as in the example logo image above).

Note: To view the splash screen on

an iPhone during a test, you must also upload the images to your CMS account. For more information about testing the skin, see Testing the customized skin for iOS, page 96.

iOS:

defaultSplashimage.png Android:

splash_screen_blank.png

iOS extended high resolution (-568h@2x suffix): 640 x 1096 px

(33)

Images used for content elements

You can customize the images used for content within the app, such as the placeholder images displayed if users have no gift cards or receipts. The table below describes the images used within the app.

The default image displayed when users view their loyalty cards in the app.

Special effects such as rounded corners and shadows are applied by the app.

image_loyalty.png iOS standard resolution: 292 x 184 px

Android: 584 x 386 px

The app’s icon. icon.png iOS standard resolution: 57 x 57

px

Android: 96 x 96 px

(34)

Description Image to customize Dimensions (height x _{width, in pixels)}

The placeholder image displayed when users have not added any gift cards.

icon_empty_giftcard.png iOS standard resolution: 139 x 139 px

iOS high resolution (@2x suffix): 278 x 278 px Android: 278 x 278 px

Note: The image

background must be set to alpha transparent.

The placeholder image displayed when users have not added any loyalty cards.

iOS:

icon_empty_loyaltycard.png Android:

icon_empty_loyalty.png

Note: The image

(35)

The placeholder image displayed when a user’s inbox is empty.

iOS:

Empty_inbox.png Android:

icon_empty_inbox.png

Note: The image

The placeholder image displayed when users have no vouchers.

icon_empty_vouchers.png iOS standard resolution: 139 x 139 px

Note: The image

The placeholder image displayed when users have no receipts.

icon_empty_receipts.png iOS standard resolution: 139 x 139 px

Note: The image

(36)

Images used for navigation elements in iOS

You can customize the images used for navigation items in the app, such as menu buttons. The table below describes the customizable images used for navigation.

(iOS only) Highlights an offer in the user’s inbox with a notification, for example, an offer that was received as a gift

MicroStrategy recommends that the color of this icon be the same as the notification_color color, described in Customizing the colors used in the app, page 28.

Note: In Android, this highlight can

be changed using the

brand_accent color code, as described in Customizing the colors used in the app, page 28.

iOS: icon_gift_accent_2.png Standard resolution: 73 x 23 px High resolution (@2x suffix): 146 x 46 px

(iOS only) Highlights an offer in the user’s inbox, for example, a special deal on items.

MicroStrategy recommends that the color of this icon be the same as the warning_color color, described in

Customizing the colors used in the app, page 28.

Note: In Android, this highlight can

be changed using the

brand_accent color code, as described in Customizing the colors used in the app, page 28.

iOS: icon_gift_accent_3.png Standard resolution: 73 x 23 px High resolution (@2x suffix): 146 x 46 px

(37)

Images used for navigation elements in Android

You can customize the images used for navigation items in the app, such as menu buttons. The table below describes the customizable images used for navigation.

The app’s Back button. icon_arrow_back.png Standard resolution: 44 x

33 px

High resolution (@2x suffix): 88 x 66 px

The arrow for the app’s Back button.

icon_arrow.png 32 x 53 px

The image used along with the app’s Back button.

(38)

Images used for navigation menu icons in iOS

In iOS, you can customize the images used for the navigation menu icons in the app. The table below describes the customizable images used for

navigation menu icons.

Changing the icon images does not change the background color for the icons. To set the background color for each image, in the skin, specify the icon_bg_color, as described in Customizing the app’s navigation menu, page 33.

MicroStrategy recommends that these images all be a consistent size and color, and use a consistent line weight. If the images are not white, make sure that the images contrast sufficiently with the background color you choose. For detailed instructions on how to customize the images in the skin, see Steps to customize the images in the skin, page 18.

Description Image to customize Dimensions (height x width, in pixels)

The icon for the Activity menu item.

icon_nav_activity.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

Note: The image must be saved as a

transparent PNG with no background color.

The icon for the More menu item.

icon_nav_more.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Gift Card menu item.

icon_nav_giftcard.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Inbox menu item.

icon_nav_inbox.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

(39)

The icon for the Store Locator menu item.

icon_nav_storelocator.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Loyalty menu item.

icon_nav_loyalty.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Vouchers menu item.

icon_nav_vouchers.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Receipts menu item.

icon_nav_receipts.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Rewards menu item.

icon_nav_rewards.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Shop menu item.

icon_nav_shop.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

The icon for the Social menu item.

icon_nav_social.png Standard resolution: up to 25 x 25 px High resolution (@2x suffix): up to 50 x 50 px

(40)

Customizing the colors used in the app

You can customize many of the colors in the app interface. For example, you can change the navigation bar so that it displays your company’s colors, or use specific colors to highlight items that are on sale.

For detailed instructions on how to customize the colors used in the app, see Steps to customize the colors used in the app, page 28.

For a list of the specific colors used in the app, see JSON name/value pairs for colors, page 29.

Steps to customize the colors used in the app

The colors in the app are defined in the skin.json file (or, for iPad, skin-ipad.json). This is a JSON (JavaScript Object Notation) file that defines the appearance of the app.

The colors are defined as hexadecimal values, of the format 0xRRGGBB, where RR is the hexadecimal value for red, GG is the hexadecimal value for green, and BB is the hexadecimal value for blue.

If you are also customizing the images in the app (see Customizing the images in the app, page 17), MicroStrategy recommends choosing colors that complement the images you are customizing. For example, if you use your company’s images for the placeholder images and navigation highlights (see Images used for content elements, page 21), make sure that colors such as brand_accent, notification_color, and warning_color

(described in JSON name/value pairs for colors, page 29) pair well with the images you choose.

Prerequisites

Before you customize the colors in your app, you should have a basic understanding of the following:

• Defining colors as hexadecimal values.

• The JSON format. For an introduction to the JSON format, see the W3Schools introduction to JSON, at

(41)

To customize the colors in the Trela demo app

1 Identify the colors in the app that you want to customize.

2 For each color, determine the hexadecimal value of your customized color.

3 In the skin.bundle folder, open skin.json (or, for iPad, skin-ipad.json) in a text editor.

4 In the JSON file, at the root level, create a colors JSON object. A fragment of the JSON file showing the colors object is shown below: { "explore": { ... }, "deep_link_prefix": "trelaExample://", "loyalty_account": { ... }, "receipt_list": { ... }, "input_validation": { ... }, "colors": { ... }, ... }

The object contains the name/value pairs that define the colors in the interface. The colors are described in JSON name/value pairs for colors, page 29.

5 Use the table in JSON name/value pairs for colors, page 29 to locate the name/value pair for the color that you want to customize.

6 In the color object, type the value for the name/value pair with the value for your customized color.

7 Save the JSON file.

JSON name/value pairs for colors

(42)

For detailed instructions on how to customize the colors used in the app, see Steps to customize the colors used in the app, page 28.

JSON name/value and description Example

text_primary

Title text for items throughout the app.

"text_primary" : "0x2a2f38"

text_secondary

Content text for items throughout the app.

"text_secondary" : "0x58595b"

brand_accent

The main accent color, which represents your brand.

Note: This color should be readable against a background of

#efefef.

"brand_accent" : "0x09a5c7"

notification_color

The accent color used for the sender of a gift.

MicroStrategy recommends that this color be the same as the icon_gift_accent_2.png image, described in Images used for content elements, page 21.

(43)

warning_color

The accent color used to highlight items, such as offers that expire soon or important information.

MicroStrategy recommends that this color be the same as the icon_gift_accent_3.png image, described in Images used for content elements, page 21.

"warning_color" : "0xe54a00"

text_button

The color of the text used on buttons.

"text_button" : "0x000000"

titlebar_top

For iOS, the top color for the title bar. For Android, the color for the entire title bar.

"titlebar_top" : "0x748193"

(iOS only)

titlebar_bottom

Bottom color for the title bar.

"titlebar_bottom" : "0x49505e"

background_shade_1

A generic medium-grey color, used for the following:

• The color of text entered in the app’s feedback message. • The border for the user’s photos.

• The background color used when users view the details of

a voucher.

• Placeholder text for all text fields in the app.

"background_shade_1" : "0xc0c0c0"

(44)

background_shade_2

A generic light-grey color, used as the background color for various sections in the app, and for progress indicators.

"background_shade_2" : "0xefefef"

(iOS only)

mail_composer_titlebar

The color of the title bar while sharing items by email

"mail_composer_titlebar": "0x000000"

(iOS only) text_badge

The text color used for unread items, such as unread offers in the Inbox.

"text_badge" : "0x2a2f38"

(iOS only) text_ribbon

The text color used for highlighted items in the Inbox. MicroStrategy recommends that this color be readable against a background of the notification_color and warning_color colors described above.

"text_ribbon" : "0xFAFAFA"

(iOS only)

text_bar_mystore

The text color used for saved stores in the My Stores section.

"text_bar_mystore": "0xFFFFFF"

(45)

Customizing the app’s navigation menu

You can customize the app’s navigation menu, depending on your needs. You can also change the order of the items displayed. The default navigation menu for the app is shown below.

This section provides instructions for the following tasks:

• Customizing the order of items in the app’s navigation menu, page 37

• Adding new items to the navigation menu in iOS, page 40

• Adding new items to the navigation menu in Android, page 41

For instructions on customizing the text in the app’s navigation menu, see Customizing the text in the app in iOS, page 65 or Customizing the text in the app in Android, page 71.

In iOS, for instructions on customizing the icon images in the app’s navigation menu, see Customizing the images in the app, page 17, in

particular the list of Images used for navigation menu icons in iOS, page 26.

Prerequisites

(46)

• The JSON format. For an introduction to the JSON format, see the W3Schools introduction to JSON, at

• The structure of the JSON used in the navigation menu, as defined in Structure of the navigation menu, page 34.

Structure of the navigation menu

The items in the navigation menu, such as Inbox, Vouchers, Receipts, and so on, are defined in skin.json (or, for iPad, skin-ipad.json), in the nav_menu array. This array contains several JSON objects, with each object in the array representing one item. For example, the JSON object for the

Inbox item is shown below: { "controller_id":1, "name_key_ios":"INBOX_ALERT", "name_key_android":"inbox", "icon":"icon_nav_inbox", "icon_bg_color":"0x423f40", "show_badge_count":1 }

The name/value pairs that can be present in the menu item object are described in the table below.

Name/Value pair Data type Required / _Optional

controller_id

Indicates the page within the app that the menu item links to. For example, 5 indicates that the menu item links to the Events page in the app.

For a list of pages and their corresponding controller IDs, see Controller IDs used in app links, page 35.

integer Required

name_key_ios

A unique ID for the menu item name, used for localization on the iOS platform.

string Optional

name_key_android

A unique ID for the menu item name, used for localization on the Android platform.

string Optional

icon

The file name, including the file extension, for an icon image to use for

(47)

Controller IDs used in app links

The table below lists the different actions that a menu item on the navigation menu can perform, and the corresponding controller ID used to link that action to a menu item.

icon_bg_color

The hexadecimal color code for the icon’s background

string (hexadecimal color code) Optional show_badge_count (iOS only)

If 1, indicates that the number of items in the page should be displayed. For example, the number of unread messages in the user’s Inbox. If 0, indicates that the number of items in the page should not be displayed.

If this name/value pair is not present, the number of items in the page is not displayed.

integer Optional

accessory_icon (iOS only)

If required, the file name for an additional icon to use for the item, displayed on the right side of the menu.

The value for accessory_icon must exclude the file extension for the icon.

string Optional

url

For links to web pages, the URL for the web page.

string Optional

Name/Value pair Data type Required / _Optional

Action Controller ID

Open the user’s Account page (iOS only)

0 Open the user’s Inbox

(iPhone and Android only)

1 Open the user’s Inbox in grid view

(iPad only)

47

Open the list of vouchers in the user’s wallet 2

Open the Receipts page, where users view the receipts for purchases they have made through the app

(48)

Open the Social tab / user’s Facebook page 14 Indicates that the item is a section that contains additional items 15

Open a list of the user’s loyalty cards 16

Open the QR code scanner 18

Open your product catalog (if the Alert app is integrated with the catalog) 24

Open the Store Locator 25

Open a list of the user’s gift cards 28

Open a list of the user’s gift cards in a grid view (iPad only)

55 Open a URL, defined in the JSON object.

The URL can be either a standard http:// or https:// URL, or an Alert alert:// deep link. For more information about deep links, including instructions to create deep links, see the Alert CMS Help.

34

Open the app’s Explore page 36

Open the Gifts page and select recipients for gifts (iOS only)

37 Open the user’s shopping cart (if the Alert app is integrated with the catalog)

(iOS only)

38 Open the Diagnostics page

(iOS only)

40 Open the Performance Monitor page

(iOS only)

41 Open the Tweet page

(iOS only)

42 Open the Pinterest page

(iOS only)

43 Open the Loyalty Activity page

(iPhone and Android only)

44 On iPad, open a split view of the Social Activity and How To Earn pages 52

Open a Web View page that requires a login 54

(49)

Customizing the order of items in the app’s navigation menu

You can rearrange the order of items in the navigation menu. For example, you can move the Loyalty item so that it appears above Vouchers and

Receipts.

To customize the order of items in the app’s navigation menu

The items in the navigation menu are defined in the nav_menu array, with each object in the array representing one item. The order of the objects in the array determines the order in which they are displayed in the app.

(50)

For example, to move the Loyalty item so that it appears above

Vouchers, first locate the JSON object for the Loyalty item.

(51)

Vouchers, move the JSON object for the Loyalty item so that it is above the Vouchers item.

To ensure that the JSON is valid, you must follow the JSON syntax conventions below:

• Ensure that the object is within the square brackets ([ ... ]) for the nav_menu array.

• Ensure that all the objects in the array, except the last object, are followed by a comma, as shown in the example below: "nav_menu": [ { //object 1 }, { //object 2 }, ... { //object n } ]

(52)

Adding new items to the navigation menu in iOS

You can also add new items to the navigation menu, by adding new JSON objects to the nav_menu array.

To add a new item to the app’s navigation menu

The items in the navigation menu are defined in the nav_menu array, with each object in the array representing one item.

2 In the nav_menu array, locate the position you want your new menu item to appear.

3 At that position, add a new JSON object for the new item, in the following format: { "controller_id":integer, "name_key_ios":"string", "icon":"string", "show_badge_count":integer, "accessory_icon":"string", "url":"string" }

For a description of the name/value pairs in the object, see Structure of the navigation menu, page 34.

For example, a menu item for a QR scanner might have the following JSON: { "controller_id":18, "name_key_ios":"SCAN_QR_MENU", "icon":"Scan_QR_icon.png" }

(53)

6 Add a <key> value from the JSON menu, using the value for name_key_ios.

For example, the QR scanner menu item’s key value would be: <key>SCAN_QR_MENU</key>

7 Add a <string> value immediately below the new <key> value, with the name of the menu option.

For example, the QR scanner menu item’s name would be: <string>QR Scanner</string>

An example of including the QR scanner item is shown below.

8 Save Localizable.strings as a UTF-8 encoded text file.

Adding new items to the navigation menu in Android

You can also add new items to the navigation menu, by adding new JSON objects to the nav_menu array.

To add a new item to the app’s navigation menu

1 In the skin.bundle folder, open skin.json in a text editor.

The items in the navigation menu are defined in the nav_menu array, with each object in the array representing one item.

2 In the nav_menu array, locate the position you want your new menu item to appear.

3 At that position, add a new JSON object for the new item, in the following format:

{

(54)

"name_key_android":"string", "icon":"string", "show_badge_count":integer, "accessory_icon":"string", "url":"string" }

For a description of the name/value pairs in the object, see Structure of the navigation menu, page 34.

For example, a menu item for a QR scanner might have the following JSON: { "controller_id":18, "name_key_android":"scanqr", "icon":"Scan_QR_icon.png" } 4 Save skin.json.

5 Open the strings.xml file using a text editor that supports UTF-8 encoding.

6 Add the following line to the JSON menu:

<string name="key">stringname</string> where:

• key is the value you used for name_key_android.

• stringname is the name of the menu option.

For example, the QR scanner menu would be:

<string name="scanqr">QR Scanner</string>.

(55)

Customizing the app’s Explore page

(56)

If you prefer a uniform look for Explore items, you can display items without a preview image, as shown below.

Prerequisites

Before you customize the Explore page, you should have a basic

understanding of the JSON format. For an introduction to the JSON format, see the W3Schools introduction to JSON, at

http://www.w3schools.com/json/json_intro.asp. To modify how items are displayed in the Explore page

1 In the skin.bundle folder, open the applicable JSON file in a text editor.

• For iPhone, open skin.json.

(57)

2 By default, items in the Explore page are displayed using template 1, which displays a preview image for each item. To display items without a preview image, change the template value to 2 using the following syntax. “explore”: {

“template”: 2 }

Customizing the app’s Inbox page

(58)

By default, each offer occupies 285 pixels vertically on the Inbox page, as in the example above. Alternatively, you can display offers in 139 vertical pixels or 80 vertical pixels.

Prerequisites

Before you customize the Inbox page, you should have a basic understanding of the JSON format. For an introduction to the JSON format, see the

W3Schools introduction to JSON, at

To modify the vertical space occupied by each offer in the Inbox

(59)

“template”: 1 }

2 By default offers on the Inbox page are displayed using template 1, which allots 285 vertical pixels for each offer. To modify the vertical space allotted to each offer, do one of the following:

• To display each offer in 139 vertical pixels, change the template value to 2. The following example offer is displayed using template 2.

• To display each offer in 80 vertical pixels, change the template value to 3.

(60)

Developer Reference. A mobile loyalty platform for retailers. Document Number: