Tech Blog

Passing Parameters in the TileSDK

We already have an blog post on passing URL parameters to AEK screens. That post can also be used to pass parameters programmatically from inside a live tile or even another AEK screen; it isn’t just limited to App Builder. Anywhere that the campusM loadaek URL scheme can be used, lets you pass parameters through. That includes TileSDK projects. See here for an overview on loadaek and other supported URL schemes.

Getting URL parameters into a live tile is possible, but requires a different approach.

Passing Parameters via Tile Config

Live tiles have access to the tile configuration – defined in App Builder – through the useTileConfig hook. This config can be customised so that we can pass new attributes through to the live tile code. Below is an example of a Canvas PI tile that’s had some configuration applied.

campusM tile config
Click to expand

By clicking on the “code” button to the right of the Tile Config block header, it displays the config as a JSON-like structure.

campusM tile config code
Click to expand

What we need to do is make changes here. Any changes we make will only be reflected in the regular “props” view if they have a corresponding property. For example, you can change tileWidth to 2 and this would be reflected correctly, but if you added a new prop of banana, this wouldn’t be (but it would still exist and can be saved to the JSON configuration block).

All TileSDK components have tileComponent set (this will also be visible in the “props” view if you have the correct permissions). What we need to add is a new block that is named after our TileSDK project. The naming convention is "packageName/TileComponent". So if my TileSDK project was called “microsoft-secondary-auth”, and the tile itself inside that project was registered as “SecondaryAuthTile”, the name for the block would be "microsoft-secondary-auth/SecondaryAuthTile". I can then add some attributes to it, like so:

campusM custom tile props
Click to expand

And after saving and publishing, the live tile can then make use of these attributes like so (as well as any others you need):

const { integrationProfileId, updateRateInSeconds } = useTileConfig();

Emulating Tile Config Locally

The walkthrough above applies to a production setting. When developing the live tile code locally with aek start, you don’t have access to App Manager to define the custom tile config you need. The good news is we can emulate this with the file runserver.yaml.

You will see in runserver.yaml a number of settings existing already. All we need to do is add to these. Following the structure of what we defined in App Builder, but tweaked slightly for the YAML format.

microsoft-secondary-auth/SecondaryAuthTile:
    integrationProfileId: 360
    updateRateInSeconds: 60

Make sure the lines are indented correctly, inline with the existing settings. Your terminal window should tell you that the new runserver config has been applied. Refresh your local web app (localhost:5000) to have the changes apply – the useTileConfig hook will now be picking up the values.

Leave a Reply