Using CodeLink
Setting up CodeLink
CodeLink is a flexible system. We will outline here the basics to getting started but if you want to modify the user experience or make further changes, then review the CodeLink Integration options.
There's three stages to setting up CodeLink :
Create a CodeLink Code
Enable CodeLink on your Tag Group
Embed the CodeLink javascript in your page(s)
Create a CodeLink Code
CodeLink Codes manage the settings for the javascript that you will add to your landing page. You can set up multiple CodeLink Codes with different settings, but you need at least one.
Go to 'Control' on the main menu and select 'CodeLink'. On the bottom right, select 'Add CodeLink Code'.
The Add CodeLink Code screen will present you with options as follows :
CodeLink Settings
CodeLink Fail URL This is the URL page on your website that any failed CodeLink check will be sent to. If, for example, the user hasn't come from an ixkio redirect link - or the link is now too old - they will be redirected to this link. If you leave this blank, then notification of the fail will be displayed directly to the user on the landing page.
Default Display HTML The CodeLink system allows you to modify the user experience during the CodeLink process, but we can also serve some HTML directly to the page via the javascript. This will display a white screen while the CodeLink check is being made. In most cases, the check is so fast that this will never show, but if there is a delay (or you don't use a CodeLink Fail URL), then this is what the user will see.
If you don't use the Default Display HTML, then you should add your own HTML code.
Verification Text This is the text that the user will see while the CodeLink check is being made. Typically, this would be 'Authentication Check In Progress' or similar. However, you can include whatever text you prefer. HTML <br> line break syntax is allowed.
Verification Text Pause Allows you to add a small pause on the CodeLink check screen while displaying the first 'Verification Text' message. This can prevent a quick flash of the authentication checking screen.
Error Codes If enabled, this will add the reason for a CodeLink fail onto the CodeLink Fail URL as query string.
Escape Word & Tag Code Override (Only available on Edit after CodeLink Code created) This will prevent the CodeLink system from giving an error state if it detects the Escape Word in the URL (not in the query string). This is designed to allow pages to be used in a development environment but not trigger the CodeLink code. For example, you could add the word 'admin' to prevent CodeLink from working in Shopify's admin pages.
Tag Code Override can be used with the Escape Word to force ixkio to use the data from a specific Tag Code. This will ignore any key used (or lack of key). This is useful for testing NFT integration via CodeLink in a development environment. Needs to be a valid XUID.
We very strongly recommend that the Escape Word is removed once the site is live. The Escape Word could prevent the CodeLink system from working in a live environment if left active.
Status Enables or disables (or deletes) this CodeLink Code. Even if the CodeLink code is inactive, the CodeLink code that you add to your website will still make a call to our servers. In some cases, if you have included the default display HTML, it will also still display the temporary blank screen and then immediately hide it. To completely disable the CodeLink code, you need to remove it from your website.
Create the Code
Click on Add to create your code. You can modify all these settings later as required.
Enable CodeLink
Tag Group > Tag Group Function Panel > CodeLink Tab
CodeLink is enabled at the Tag Group level (and by enabling your CodeLink Code).
Select Status as either Enabled or Disabled.
If your CodeLink Code is enabled (Side Menu > Control > CodeLink) and on your landing page, then CodeLink will still be active even if you disable CodeLink at the Tag Group level. To completely disable CodeLink on your landing page you need to disabled the CodeLink Code itself.
If CodeLink is On, then an additional unique key will be automatically added to your redirect URL. The parameter for this is ixr. For example, if your standard redirect URL was :
Then it will become (for example) :
If you have other query string elements either as part of your link or dynamically added via Dynamic Response, then the CodeLink key will be added to the end of the query string.
Add the Javascript to your page
You need to add the following code to your authentication landing page :
Where <yourcode> will be replaced by the CodeLink Code you created in step 1. For example, if your CodeLink Code was dRzABK, then your javascript woudl be :
You can add the code anywhere you choose, for example in the <head> section or before the end of the <body> section.
CodeLink Flow
The Process
CodeLink has the following flow :
User scans the NFC tag which directs them to ixkio
Ixkio handles the authentication check and redirects to your auth page. Ixkio will add a unique CodeLink Key into the URL.
Your page will load the CodeLink Javascript which will either :
Display our Default Display HTML Overlay or
Display your HTML
The CodeLink Javascript will then make a call to our server to verify the CodeLink Key. This will response either as :
A pass, in which case :
The CodeLink Javascript will simply close our Default Display Overlay or
The script will hide your HTML and/or
The script will trigger your javascript function
A fail, in which case :
The Trackback Javascript will display a fail message via our Default HTML Overlay or
The script will redirect instantly to your CodeLink Fail URL or
The script will trigger your javascript function
Why CodeLink might fail
If a user attempts to access your auth page directly without any CodeLink Key in which case it will trigger a 'No Key' error.
If a user attempts to re-use a link to your auth page with a CodeLink Key, in which case either :
If the attempt is made quickly (but slower than a normal page hit), then it will trigger an 'Expired Key' error.
If the attempt is made a substantial time later, then it will trigger an 'Key Not Found' error
If the user attempts to access the page with an incorrect CodeLink Key, then either:
It will trigger a 'Key Not Found' error, if it looks like it might be a real key or
It will trigger a 'Key Error' error.
The Display
If the Default Display HTML is selected, then ixkio will serve a few lines of HTML code along with the javascript.
This HTML code will attempt to display a full page white overlay onto your page and display the 'Authentication Text' (typically, Authentication Check In Progress). Under normal use - providing it's a valid attempt to view your page from a redirect - then this will only show for the briefest of moments and the overlay will be removed.
If the CodeLink check does not pass, then :
If a CodeLink Fail URL has been entered in your settings, then the user will be redirected to this page
If a CodeLink Fail URL has not been entered in your settings, then a message will be presented to the user (on the white overlay) of either :
No CodeLink Key (when no Key has been provided)
CodeLink Key Error (if the key is of the wrong format)
CodeLink Key Expired (if the key is too old to be used)
CodeLink Key Not Found (this can mean that the key is the right format but not correct or it can mean that the key was very old and has been removed from the ixkio platform)
Last updated