Tile Information Service

The Spark® App Launcher optionally allows custom application and user-specific text to be displayed on the face of the application's tile. For example, an application may show that the user has 3 new leads, has 4 upcoming reminders, etc. Currently, the data is can only be displayed in text format, but we hope to include other options like charts, tables, and links in the future.

Step 1: Provide a Dashboard Tile Request URI

When adding your app to the Spark Store, make sure to provide a Dashboard Tile Request URI. When a user loads their Spark Launcher, we will use this URI to make a request to you for information.

You can also select options that will appear on the back of the Tile in the Spark Launcher. These can be used to give the user an option as to what data should be shown on the tile.

The Option Name text will be shown to the user in a drop down on the back of the application's tile. The URI Parameter will be appended to the Dashboard Tile Request URI that you provide when setting up your application. See below for more details.

Step 2: Request Format

http://my-app.com/tile_information?launcher_token=e2e42a07550863f8b67f5eb252581f6d&selected_parameter=todo_count&callback=sparkTileInfo123

When the Spark Launcher makes a request to your URI, it will provide you with a launcher_token and the value of the parameter the user has selected (if available). You can use this in the last step to retrieve the user's AccountId, which you can then use to retrieve any user specific data that you would like to show on the tile.

Step 3: Request User `AccountId` (Optional)

If the text you wish to display on the tile is the same for all users of your application, then there is no need to request the user's AccountId and you may proceed to step 4. But, if you wish to customize the text based on what user is viewing your application's tile, follow the instructions in this step.

Now that you have a launcher_token, you can make the verification request back with the token to the following URI:

http://sparkplatform.com/dashboard/users?launcher_token=[launcher_token]

If successful you should be provided the user's actual AccountId in the following format:

{
  D: {
    Success: true,
    AccountId: 00000000000000000000000000
  }
}

Note: The launcher_token persists for 60 seconds, so that's how long you have to make this request after receiving the token.

Step 4: Return the desired tile data

Now all you have to do is return the text you want to appear on the tile in JSONP format. You can use the 'callback' url parameter passed in Step 2 to set the callback function. The maximum length is restricted at 140 characters and no HTML is allowed. Using "|" for a line break is supported, as documented below.

sparkTileInfo123({
  "Text": "Click here to start your first Todo"
})

Note: This entire request timeout (Step 1 through Step 4) is 10 seconds. If for some reason it takes longer, the place where the user- or application-specific text normally displays on the tile will be rendered blank, but the rest of the tile will otherwise be rendered normally.

Formatting Options

Currently only text is supported on the tile face, but you can use a "|" (pipe) for creating a line break in the text. If the only text preceding the first pipe is an integer (up to four digits), the integer will be enlarged: