QR code guide
When a user scans a Rogerthat QR code, his smartphone will send a messaging.poke request to the TPS (Third Party Service) that created the QR code. The request will contain the tag that was baked into the QR Code.
The TPS will typically react on this user action, by starting a message flow to that user, or by completing some kind of transaction.
Important to know:
- A user can scan a Rogerthat QR code using any barcode reader on his smartphone.
- A user who does not have the Rogerthat Messenger app installed on his smartphone, will be redirected to the Rogerthat app page in the Apple Appstore or Android Market, from where he can install the Rogerthat app.
- A barcode reader is included in the Rogerthat smartphone app – check the “Scan” tab.
Example QR Code Templates
We present three QR Code Templates, which can be downloaded. They are a good starting point to modify colors, add text or add a logo.
Note that the gray areas are in fact transparant.
Creating your own QR Code Templates
QR Code templates are configured in the Service Control Panel menu QR Code Branding.
Rogerth.at QR Code templates have the following properties:
- Description of the template
- The QR code body contains white square dots and colored square dots. The color is configurable. You should pick a color which contrasts well with white.
- (optional) Template overlay image. This is a 348 (width) x 343 (height) PNG image. See downloadable examples in the previous section. The QR Code will be generated, and the overlay image will be placed on top of the QR Code.
- Once created, a QR Code template gets a key and a creation timestamp
Rogerth.at QR Codes are generated in a 2-phase process:
- First the QR Code is generated with colored dots on a white background
- Dot color is configurable
- The QR Code has size 250 x 250 pixels. This is 25 x 25 dots of each size 10 x 10 pixels
- The QR Code is placed at offset (40, 40) in a PNG of size 348 x 343 pixels (counting from left top). Right bottom point of the QR Code is at position (290, 290)
- Next, an optional QR Code Template is placed as an overlay on top of the generated QR Code. The QR Code Template must contain a transparant area for the inner body of the QR Code, which contain the data dots
Creating a QR Code Template happens in the QR Code Branding Service menu. The description, dot color and optional template image can be configured to create a new template. Once the template is created, one can preview or delete it, or create a QR Code based on the template.
Best practices for optimal scannability:
- For optimal contrast, choose a dark color for the colored data dots
- Leave the white 40 pixel border empty on top and at the left side of the QR Code
- Rules of thumb for the 3 large squares-in-square:
- The squares are 70 x 70 pixels in size each, with an inner square of 30 x 30 pixels
- The squares are placed at offsets (40, 40); (40, 250); (250, 40)
- Use dark colors
- Do not apply a color gradient to the inner squares
- It is ok to put branding at the bottom and in the right bottom corner of the QR Code. See examples
Creating QR Codes
When you create an Action QR Code, a description and a tag have to be added to the QR Code definition.
When a user scans the QR Code, he will see the description on the poke button. When he clicks this button, the TPS will receive the callback messaging.poke containing the poke tag that was included in the QR Code.
Hence for every created QR Code, the developer should make sure that the TPS will handle this poke tag correctly in the messaging.poke callback.
Creating a QR Code using the Service Control Panel
A QR Code can be created directly from a QR Code Template by clicking the link Create new QR Code from this template. A form pops up in which the description and poketag of the QR Code have to be entered.
An alternative way to create QR Codes is to select menu option My QR Codes and to click the button Create New (at right top of screen). Apart from description and tag, the QR Code Template has to be selected
Creating a QR Code using the API
When a large number of QR Codes have to be generated, the only practical way is to do it programmatically:
- API call qr.create
- description: user-visible caption of the interaction button
- tag: reference tag that will be received by the Third Party Service
- template_key: key of the QR Code Template
Check the API Reference for the complete documentation.
Processing a QR code scan
When a user scans a QR code, the API calls sent to the TPS are slightly different, depending on whether the user was already connected to the TPS or not: