Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
blocks:advanced_scripting:visitor_identity_tracking [2022-05-09 13:19] admin Documented deleteRecord instead of $delete |
blocks:advanced_scripting:visitor_identity_tracking [2023-01-23 09:23] (current) admin Added link toapp notes |
||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Visitor | + | ====== Visitor |
A Visitor Spot in Blocks can be used as a basic entry point for visitors to connect to the system. This is essentially a URL allowing a number of visitors to all connect to the same Visitor Spot. The URL looks something like this: | A Visitor Spot in Blocks can be used as a basic entry point for visitors to connect to the system. This is essentially a URL allowing a number of visitors to all connect to the same Visitor Spot. The URL looks something like this: | ||
Line 30: | Line 30: | ||
By selecting " | By selecting " | ||
- | - For //each individual visitor//, independent control over child blocks, parameters, tags, custom CSS classes, etc, similar to what you have for Display Spots. | + | - For //each individual visitor// |
- | - The ability to collect | + | - The ability to collect data on each individual visitor, such as any data being entered by that visitor, spots being visited, |
By combining these two abilities, you can do things such as presenting different content to a visitor depending on where she's been during her visit, points earned along the way, or any other data provided or collected during the visit. Such data can also be archived after the visit for subsequent analyzation, | By combining these two abilities, you can do things such as presenting different content to a visitor depending on where she's been during her visit, points earned along the way, or any other data provided or collected during the visit. Such data can also be archived after the visit for subsequent analyzation, | ||
Line 52: | Line 52: | ||
- Create a Blocks user script (see below) defining the type of data to record. | - Create a Blocks user script (see below) defining the type of data to record. | ||
- Select " | - Select " | ||
- | - Enter the name of the data record in the " | + | - Enter the type-name of the data record in the " |
=== Using an Identification Token === | === Using an Identification Token === | ||
- | Here, a unique identification token is handed out to each visitor at the entrance. This token could for example be an RFID bracelet och tag, carried by the visitor. By scanning this token at desired | + | Here, a unique identification token is handed out to each visitor at the entrance. This token could for example be an RFID bracelet och tag, carried by the visitor. By scanning this token at stations, Blocks will learn who's where, and can collect and act on this information. The token may be returned when leaving, |
This arrangement removes the need for visitors to have and use a personal mobile phone. Depending on the information collected during the visit, this may also remove any privacy issues (assuming no personally identifiable information is collected). More on this below. | This arrangement removes the need for visitors to have and use a personal mobile phone. Depending on the information collected during the visit, this may also remove any privacy issues (assuming no personally identifiable information is collected). More on this below. | ||
- | The visitor can still have a personalized experience, based on where she's been or interactions performed or information entered at visited spots. Personalized information can be presented | + | The visitor can still have a personalized experience, based on where she's been or interactions performed or information entered at visited spots. Personalized information can be shown on Display Spots as the visitor presents the identification token (e.g., scans the RFID bracelet). |
To use this method, do as follows: | To use this method, do as follows: | ||
- Create a Blocks user script (see below) defining the type of data to record. | - Create a Blocks user script (see below) defining the type of data to record. | ||
- | - Select " | ||
- | - Enter the name of the data record in the " | ||
- Connect the desired number of token scanners (RFID, or similar) to Blocks. | - Connect the desired number of token scanners (RFID, or similar) to Blocks. | ||
- Scan the token when handing it out to the visitor. | - Scan the token when handing it out to the visitor. | ||
Line 73: | Line 71: | ||
Now, as the visitor scans the token at desired spots, Blocks will learn about this and can take actions as desired (including presenting personalized interactions at display spots). | Now, as the visitor scans the token at desired spots, Blocks will learn about this and can take actions as desired (including presenting personalized interactions at display spots). | ||
- | To scan the tokens, you can use either | + | To scan the tokens, you can use stand-alone scanners connected to the network, managed by a Device Driver in Blocks. Or use a Display Spot with a keyboard-emulating scanner connected to its USB port. Set the Display Spot to use " |
- | IMPORTANT: If tokens are reused, make sure tokens are disassociated from their visitors. This can be done in one or more of the following means: | + | IMPORTANT: If tokens are reused, make sure tokens are disassociated from their visitors. This can be done by one or more of the following means: |
* When returned at the exit, by canning it in a specific "exit scanner" | * When returned at the exit, by canning it in a specific "exit scanner" | ||
* When handed out to another visitor. | * When handed out to another visitor. | ||
- | * En masse, for all tokens, once every night. This method assumes tokens aren't re-used the same day. | + | * En masse, for all tokens, once every night. This method assumes tokens aren't re-used |
=== Using a Combination of Token and Mobile Phone === | === Using a Combination of Token and Mobile Phone === | ||
- | This method is essentially the same as the previous one, but with the additional ability of also associating a mobile phone with the same visitor. This may allow for basic tracking and personalized experience using the token, while using an (optional) mobile phone to augment | + | This method is essentially the same as the previous one, but with the additional ability of also associating a mobile phone with the same visitor. This provides |
To use this method, do as follows: | To use this method, do as follows: | ||
Line 96: | Line 94: | ||
- Optionally, also scan the visitors mobile phone. This can be done using a QR code shown on the phone. This links the mobile phone to the same data record as identified by the token. | - Optionally, also scan the visitors mobile phone. This can be done using a QR code shown on the phone. This links the mobile phone to the same data record as identified by the token. | ||
- | You'll then use the token at each station to identify yourself. The optional mobile phone can be used as feedback (e.g., scores at game stations) or to enter information that will then go into the visitor' | + | You'll then use the token at each station to identify yourself. The optional mobile phone can be used as feedback (e.g., scores at game stations) or to enter additional |
==== Privacy Issues ==== | ==== Privacy Issues ==== | ||
- | Depending on what information you collect and the jurisdiction in your country, you may need to pay attention to privacy regulations, | + | Depending on what information you collect and the laws governing |
===== User Script ===== | ===== User Script ===== | ||
- | To utilize the individual | + | To create a // |
==== Data Record Declaration ==== | ==== Data Record Declaration ==== | ||
- | A key function | + | A key feature |
< | < | ||
Line 122: | Line 120: | ||
</ | </ | ||
- | The name of this record type is " | + | The name of this record type is " |
- | In addition to the fields | + | In addition to the fields |
=== Record Field Decorators === | === Record Field Decorators === | ||
- | As mentioned above, each field in the record must be marked with the @field() decorator, as you can see above. In addition to this mandatory | + | As mentioned above, each field in the record must be marked with either a @field() an @id() decorator. In addition to these mandatory |
- | * **@spotParameter()** marks the field as an alias of a Spot Parameter. | + | The **@id()** decorator indicates that the field is to be used as a secondary key (an " |
- | * **@id()** marks the field as holding | + | |
- | The **@spotParameter()** decorator causes data stored in the record to be linked to a spot parameter with the same name. You must establish this spot parameter separately, making sure it has the same name and data type as the record field. This can be done either | + | A **@spotParameter()** decorator causes data stored in the record to be linked to a Visitor Spot parameter with the same name and data type. This must be used together with the @field() decorator, as shown above. You must establish this parameter separately, making sure it has the same name and data type as the record field. This must be done in the Block assigned |
- | The **@id()** decorator indicates that the field is to be used as a secondary key (an " | + | ==== Creating and Finding Records ==== |
- | === Data Record Storage === | + | When using a mobile phone (i.e., a Visitor Spot) as the only identifier of a visitor, the associated data record is implicitly created when the visitor connects to Blocks. A ' |
- | In addition | + | When using other means of visitor identification, |
- | Inside that record instance directory, you'll find at least a file named " | + | When using a combination of identity token and mobile devices, you need to find a way by which both these methods of identification can be bound to the same record. In this case, you must use two separate @id() fields, one holding the token' |
+ | |||
+ | === Visitor Lifecycle === | ||
+ | |||
+ | Note that the Visitor object, provided when a visitor' | ||
+ | |||
+ | While the Visitor object will come and go as the visitor' | ||
+ | |||
+ | ==== Data Record Storage ==== | ||
+ | |||
+ | In addition to being available inside your user script, data records are also stored on disk inside the //record// directory located in your Blocks root directory. Inside this record directory, Blocks creates one sub-directory per record type, named by the record type (" | ||
+ | |||
+ | Inside that record instance directory, you'll find at least a file named " | ||
* Time of arrival. | * Time of arrival. | ||
Line 148: | Line 157: | ||
* Name, game scores, or any other data you chose to collect along the way. | * Name, game scores, or any other data you chose to collect along the way. | ||
- | You must not modify | + | You must not remove or change |
- | === Data Record Clean-up === | + | ==== Data Record Clean-up |
Once a visitor leaves, this data must be discarded to not consume excessive amounts of server memory as new visitors join in. Your user script must manage this clean-up of visitor data records, either one by one (as each visitor leaves or any identifying token is recycled) or en masse once closed for the day (e.g., at 3:00am every day). | Once a visitor leaves, this data must be discarded to not consume excessive amounts of server memory as new visitors join in. Your user script must manage this clean-up of visitor data records, either one by one (as each visitor leaves or any identifying token is recycled) or en masse once closed for the day (e.g., at 3:00am every day). | ||
- | This data record clean-up can either simply delete the record(s) or archive them. Use the archive method if you intend to use the data for further analysis of visitor' | + | This data record clean-up can either simply delete the record(s) or archive them. Use the archive method if you intend to use the data for further analysis of visitor' |
- | + | ||
- | To remove individual records, call the deleteRecord function on the user script. Pass //true// as the second parameter to the deleteRecord function to archive the record rather than deleting it. To remove all records of a particular type, call the deleteRecords function on the user script, passing it the record type and a second optional boolean parameter set to true to archive the records (if desired). See the declarations of these functions in the Script.ts system_lib file for details. | + | |
+ | To remove individual records, call the **deleteRecord** function on the user script, passing it the record to discard. Pass //true// as the second parameter to archive the record rather than deleting it. To remove //all// records of a particular type, call the **deleteRecords** function on the user script, passing it the record type and a second optional boolean parameter set to true to archive the records (if desired). See the declarations of these functions in the Script.ts file in system_lib for details. | ||
==== Other User Script Functions ==== | ==== Other User Script Functions ==== | ||
Line 166: | Line 174: | ||
* A mechanism to clean up data records, as described above. This can be done one by one as visitors leave or tokens are recycled, or en masse once every night. Such a nightly clean-up can be exposed as a public function marked with @callable(), | * A mechanism to clean up data records, as described above. This can be done one by one as visitors leave or tokens are recycled, or en masse once every night. Such a nightly clean-up can be exposed as a public function marked with @callable(), | ||
- | In addition to these mandatory functions, you most likely will have additional functions performing your desired logic as visitors arrive at certain | + | In addition to these mandatory functions, you most likely will have additional functions performing your desired logic as visitors arrive at spots, interact with objects, enter data on their mobile phones, etc. The details here depend entirely on your own requirements. |
- | + | ||
- | + | ||
- | + | ||
- | + | ||
+ | ===== Where to go from Here ===== | ||
+ | Here are a few [[blocks: | ||