QrCodes
Create and update dynamic QR Codes programatically and start building engaging solutions. Generate valuable data each time the QR code is scanned.
Openscreen QR Codes are created against an Asset. They can be created at the same time as an Asset, or they can be created after the fact against an existing assetId. An Asset Object represents the physical object being scanned and the QR Code Object determines the operation being performed when a QR Code image is scanned.
Openscreen offers both static and dynamic QR Codes:
Dynamic QR Codes can be tracked, updated, and modified over their lifecycle. They can redirect a user to a different location based on the status of a QR Code, who the scanner is, and much more. Dynamic QR Codes provide the capabilities for asset and contact management of physical and digital products.
Static QR Codes are the most basic QR Code available. They can redirect a user to a URL, send an email, or send an SMS. Static QR Codes do not offer tracking capabilities such as providing visibility on the number of scans, location of scans, or who is scanning it.
Bulk QR Generation: Using the Openscreen platform you can bulk generate up to 150 unique QR Codes at once.
Intent and Intent State
Dynamic QR Codes can be programmed using the Intent State and Intent attributes. An Intent State can be used to determine how a user is redirected when they scan a QR Code. For example, if you have a product that does not have an owner, set the Intent State to "Pending Ownership". The Intent State can be changed to "Owner" once a user has claimed ownership of the product. The Intent attribute allows you to input an operation that will determine how a QR Code reacts when it is scanned. For example, if the person scanning the QR Code is the owner of the product then they can access all of the information on his/her product and have the capability to transfer ownership. If the person scanning the QR Code is not the owner, then he/she can be presented with the basic product information along with the owner's name.
Intent Types
There are 2 different intent types that can be used for your QR Code. The intent type determines the type of redirect that will occur when a QR Code is scanned.
The 2 intent types are:
STATIC_REDIRECT:Redirect a user directly to the intent address without capturing any information.DYNAMIC_REDIRECT:Redirect a user to the intent address while first capturing scan data and generating a Scan Object. Using Dynamic Redirect, there are no changes or updates made to a QR Code.
Dynamic Redirect Types
NO_SCAN_ID:The user is redirected to the QR Code intent and a Scan Object is generated.SCAN_ID_IN_PATHPARAMETER:The user is redirected to the QR Code intent and a Scan Object is captured. The Scan ID will be added to the URL as a path parameter. This means that when a user scans the QR Code, the scanId will be appended to the intent (URL) that the scanner is directed to upon scan. For example, if the intent of the web application that you created has the URL 'https://www.myrealestatelisting.com'. The user will be taken to a final destination of 'https://www.myrealestatelisting.com/scanId'. Example: 'https://www.myrealestatelisting.com/c262c53e-3ec0-4f48-823e-de5539dd85dc'. Choosing this QR Code parameter will allow your application to understand which QR Code was scanned when taking the user to your web application. Knowing which QR Code was scanned will allow you to create asset & contact relationships, update your QR Code, and much more.SCAN_ID_IN_QUERY_STRING_PARAMETER: The user is redirected to the QR Code intent and a Scan Object is captured. The Scan ID will be added to the URL as a query string parameter. This means that when a user scans the QR Code, the scanId will be appended to the intent (URL) that the scanner is directed to upon scan. For example, if the intent of the web application that you created has the URL 'https://www.myrealestatelisting.com'. The user will be taken to a final destination of 'https://www.myrealestatelisting.com?scanId'. Example: https://www.myrealestatelisting.com?c262c53e-3ec0-4f48-823e-de5539dd85dc. Choosing this QR Code parameter will allow your application to understand which QR Code was scanned when taking the user to your web application. Knowing which QR Code was scanned will allow you to create asset & contact relationships, update your QR Code, and much more.
Status - Inactive vs. Active
QR Codes can be toggled between Active and Inactive. This feature can be particularly useful when using QR Codes for dynamic campaigns. When a QR Code is made Inactive, the individual who scans it is no longer brought to the pre-established intent for that QR Code; instead, the individual is redirected to a page informing them that the QR Code is not currently active. Inactive QR Codes do not track scan data allowing for data tracking only when the campaign is active. When the campaign is up and running again, the QR Code can be brought back to an Active status and when it is scanned, the individual is brought to the intent (destination) of the QR Code upon scanning. Toggling between an Active and Inactive status can increase the longevity of QR Codes and reduce costs associated with creating and distributing new physical QR Codes for each campaign. When QR Codes are created they are automatically set to an Active status.
Attributes
Get Qr Codes By Account Id
Retrieves QR Codes associated to an Openscreen Account.
The number of QR Codes retrieved can be modified using the 'limit' field for up to 100 per request. The next batch of QR Codes can be retrieved using the 'lastKey' field - a hashed key that points to the last object of the current batch.
Returns
Returns a list of QR Codes objects associated to an Openscreen accountId. Throws an error if the accountId is invalid.
1
const QRCodes = await os.account(accountId).qrCodes().get();{
"entity_type": "get_qr_codes_by_account_id.response_body",
"account_id": "xxxxxxxxxxxxxxxxxxxxx",
"last_key": "xxxxxxxxxxxx",
"number_of_qr_codes": 2,
"qr_codes": [
{
"locator_key_type": "SHORT_URL",
"intent": "https://sidewalkqr.com/123main",
"scan_count": 0,
"locator_key": "xxxxxxxx",
"qr_code_id": "85d1cf38-846a-4816-80bb-fb7fff167004",
"status": "ACTIVE",
"intent_type": "DYNAMIC_REDIRECT",
"asset_id": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"created": "2021-11-29_t14:09:56_z",
"image": {
"data": "data:image/png;base64iVboWrw0Kg...",
"options": {
"scale": "12",
"color": {
"dark": "#0a74b7",
"light": "#ffffff"
},
"data_url": True,
"format": "png"
}
},
{
"locator_key_type": "SHORT_URL",
"intent": "https://sidewalkqr.com/123main",
"scan_count": 0,
"locator_key": "xxxxxxxxxxx",
"qr_code_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ACTIVE",
"intent_type": "DYNAMIC_REDIRECT",
"asset_id": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"created": "2021-12-223_t14:09:00_z",
"image": {
"data": "data:image/png;base64iVboWrw0Kg...",
"options": {
"scale": "12",
"color": {
"dark": "#0a74b7",
"light": "#ffffff"
},
"data_url": True,
"format": "png"
}]
}
}Create Qr Code By Asset Id
Creates a new QR code in the linked Asset. Openscreen currently offers short url as a type of locator key. The locator key is used to locate Assets and Contacts that are related to a QR Code upon scan.
Request Object
Returns
Returns a QR code object containing a unique qrCodeId which can be used to Get QR Code image. Throws an error if the assetId is invalid.
1
2
3
4
5
6
7
const qrCode = await os.asset(assetId).qrCodes().create({
intentState: { state: 'Pending Ownership' },
intent: 'https://openscreen.com',
dynamicRedirectType: "NO_SCAN_ID",
intentType: 'DYNAMIC_REDIRECT',
locatorKeyType: "SHORT_URL"
});
{
"entityType": "create_qr_code_by_asset_id.response_body",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"qrCode": {
"entityType": "app.qr-code",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"qrCodeId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ACTIVE",
"locatorKeyType": "SHORT_URL",
"locatorKey": "string",
"intentType": "DYNAMIC_REDIRECT",
"intent": "https://openscreen.com",
"intentState": {
"state": "Pending Ownership"
},
"qrCodeId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"locatorKey": "xxxxxxxxxxx"
}
Get Qr Codes By Asset Id
Retrieves all QR Codes for an asset. A unique assetId must be supplied in the request.
You may pass ImageOptions in this call to customize the QR code image. Doing so will merge the new format with the existing format of the image.
Returns
Returns a list of all QR Code objects for an Asset.
1
const qrCodes = await os.asset(assetId).qrCodes().get();
{
"assetId": "assetId": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"numberOfQrCodes: 2,
"qrCodes": [{
"locatorKeyType": "SHORT_URL",
"intent": "https://sidewalkqr.com/123main",
"scanCount": 0,
"locatorKey": "sP4axnyCfSV",
"qrCodeId": "85d1cf38-846a-4816-80bb-fb7fff167004",
"status": "ACTIVE",
"intentType": "DYNAMIC_REDIRECT",
"assetId": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"created": "2021-11-29T14:09:56Z",
"image": {
"data": "data:image/png;base64,iVBORw0KG...",
"options": {
"scale": "12",
"color": {
"dark": "#0a74b7",
"light": "#ffffff"
},
"dataUrl": "true",
"format": "png"
}
},
{
"locatorKeyType": "SHORT_URL",
"intent": "https://sidewalkqr.com/123main",
"scanCount": 0,
"locatorKey": "xxxxxxxxxxx",
"qrCodeId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ACTIVE",
"intentType": "DYNAMIC_REDIRECT",
"assetId": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"created": "2021-12-223T14:09:00Z",
"image": {
"data": "data:image/png;base64,iVBORw0KG...",
"options": {
"scale": "12",
"color": {
"background": "#0a74b7",
"foreground": "#ffffff"
},
"dataUrl": "true",
"format": "png"
}
}
]
}Get Qr Codes By Project Id
Retrieves QR Codes associated to a Project. The number of QR Codes retrieved can be modified using the 'limit' field for up to 100 per request. The next batch of QR Codes can be retrieved using the 'lastKey' field - a hashed key that points to the last object of the current batch.
Returns
Returns a list of QR code objects for a project. Throws an error if the projectId is invalid.
1
const projectQRCodes = await os.project(projectId).qrCodes().get();{
"entityType": "get_qr_codes_by_project_id.response_body",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"lastKey": "xxxxxxxx",
"numberOfQrCodes": 2,
"qrCodes": [
{
"qrCode": {
"intent": "https://sidewalkqr.com/123main",
"locatorKeyType": "SHORT_URL",
"scanCount": 4,
"modified": "2021-10-14T16:03:29.984Z",
"locatorKey": "xxxxxxxxxxx",
"qrCodeId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"intentType": "DYNAMIC_REDIRECT",
"assetId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"entity": "app.qr-code",
"created": "2021-10-14T14:15:47.389Z"
},
"qrCode": {
"intent": "https://sidewalkqr.com/123main",
"locatorKeyType": "SHORT_URL",
"scanCount": 1,
"modified": "2021-11-14T16:03:29.000Z",
"locatorKey": "xxxxxxxxxxx",
"qrCodeId": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"intentType": "DYNAMIC_REDIRECT",
"assetId": "xxxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,
"entity": "app.qr-code",
"created": "2021-11-14T14:15:47.389Z"
}
]
}
Delete Qr Code
Deletes a QR code. A valid qrCodeId must be passed in the request.
Returns
Returns the recently deleted QR Code object. Throws an error if the qrCodeId is invalid.
1
const deleteQrCode = await os.qrCode(qrCodeId).delete();{
"entityType": "delete_qr_code.response_body",
"qrCode": {
"entityType": "app.qr-code",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"qrCodeId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"status": "ACTIVE",
"locatorKeyType": "SHORT_URL",
"locatorKey": "string",
"intentType": "DYNAMIC_REDIRECT",
"intent": "https://openscreen.com",
"intentState": {
"state": "Pending Ownership"
},
"dynamicRedirectType": "NO_SCAN_ID",
"scanCount": 3,
"qrCodeId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"locatorKey": "xxxxxxxxxxx"
}
}Get Qr Code
Retrieves the QR Code image file. This image can be accessed using multiple methods:
Download the QR Code as a PNG file into your local project directory by including a convenience function after your QR Code has been generated. Include the following line of code after calling Get QR Code. ``` await os.saveQrImageDataToFile(qrCode, 'my-qr-code.png') ```
Retrieve a base64 image url within your return object by including, ` dataUrl: true` in your Get QR Code call.
Retrieve a base64 data string within your return object when using the Get QR Code call by excluding the prior steps.
QR code customization: Passing ImageOptions in this call will append to the existing customization of the QR code. In the example shown to the right, the background of the QR code will be changed to Black and the foreground changed to White. Any other customizations, including the logo in the QR code, will remain as-is. If no ImageOptions are specified, the QR code customizations remain unchanged.
Returns
Returns a QR code image in the specified format. Throws an error if the qrCodeId is invalid.
1
2
3
4
5
6
7
8
9
10
const qrCode = await os.qrCode(qrCodeId).get({
format:'PNG',
scale: 12,
background: '#ffffff',
foreground: '#000000',
dataUrl: true
});
// Include the following line of code if you would like to save the QR Code locally to your project directory
await os.saveQrImageDataToFile(qrCode, 'my-qr-code.png');
{
"entityType": "get_qr_code.response_body",
"locatorKeyType": "SHORT_URL",
"intent": "https://sidewalkqr.com/123main",
"scanCount": 0,
"locatorKey": "sP4axnyCfSV",
"qrCodeId": "85d1cf38-846a-4816-80bb-fb7fff167004",
"status": "ACTIVE",
"intentType": "DYNAMIC_REDIRECT",
"assetId": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"created": "2021-11-29T14:09:56Z",
"image": {
"data": "data:image/png;base64,iVBORw0KG...",
"options": {
"scale": "12",
"color": {
"background": "#ffffff",
"foreground": "#000000"
},
"dataUrl": "true",
"format": "png"
}
}
}Update Qr Code
Updates the attributes of a QR Code with the exception of locator key. This update overwrites the previously stored values.
QR code customization: Passing ImageOptions in this call will over-write the existing customization of the QR code. If no ImageOptions are specified, the QR code customizations remain unchanged. You can revert the customizations to the default values by passing ImageOptions as an empty object.
QR Codes can also be toggled between an Active and Inactive status using this method.
Request Object
Returns
Returns the updated QR Code object with any new ImageOptions, if any. The unique identifier qrCodeId remains unchanged. Throws an error if the qrCodeId is invalid.
1
2
3
4
const qrCode = await os.qrCode(qrCodeId).update({
intent: "https://openscreen.com",
format: "PNG",
});
{
"entityType": "update_qr_code.response_body",
"qrCode": {
"entityType": "app.qr-code",
"created": "2021-11-29T14:09:56.000Z",
"assetId": "a3c463a0-7038-41ec-bdef-2fab29c22cc5",
"qrCodeId": "85d1cf38-846a-4816-80bb-fb7fff167004",
"status": "ACTIVE",
"locatorKeyType": "SHORT_URL",
"locatorKey": "sP4axnyCfSV",
"intentType": "DYNAMIC_REDIRECT",
"intent": "https://openscreen.com/",
"scanCount": 0,
"image": {
"data": "data:image/png;base64,iVBORw0KG...",
"options": {
"color": {
"background": "#000000",
"foreground": "#ffffff"
},
"dataUrl": "true",
"format": "PNG"
}
}
}