Using Traceback
Traceback 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 Traceback Integration options.
There's three stages to setting up Traceback :
- Create a Traceback Code
- Enable Traceback on your Tag Group
- Embed the Traceback javascript in your page(s)
Traceback Codes manage the settings for the javascript that you will add to your landing page. You can set up multiple Traceback Codes with different settings, but you need at least one.
Go to 'Control' on the main menu and select 'Traceback'. On the bottom right, select 'Add Traceback Code'.
The Add Traceback Code screen will present you with options as follows :
Traceback Fail URL
This is the URL page on your website that any failed Traceback 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 Traceback system allows you to modify the user experience during the Traceback process, but we can also serve some HTML directly to the page via the javascript. This will display a white screen while the Traceback 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 Traceback 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.
Authentication Text
This is the text that the user will see while the Traceback 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.
Authentication Text Pause
Allows you to add a small pause on the Traceback check screen while displaying the first 'Authentication Text' message. This can prevent a quick flash of the authentication checking screen.
Error Codes
If enabled, this will add the reason for a traceback fail onto the Traceback Fail URL as query string.
Escape Word & Tag Code Override (Only available on Edit after Traceback Code created)
This will prevent the Traceback 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 Traceback code. For example, you could add the word 'admin' to prevent Traceback 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 Traceback 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 Traceback system from working in a live environment if left active.
Status
Enables or disables (or deletes) this Traceback Code. Even if the traceback code is inactive, the traceback 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 traceback code, you need to remove it from your website.
Click on Add to create your code. You can modify all these settings later as required.
Tag Group > Tag Group Function Panel > Traceback Tab
Traceback is enabled at the Tag Group level. Only Tag Groups with Authentication tags will have this option.
Select Status as either On or Off.
If Traceback 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 : https://yourdomain.com/authsuccess
Then it will become (for example) :
https://yourdomain.com/authsuccess?ixr=e97f8xrvzbsw4by7
If you have other query string elements either as part of your link or dynamically added via Dynamic Response, then the Traceback key will be added to the end of the query string.
You need to add the following code to your authentication landing page :
<script defer src="https://t.ixkio.com/s/traceback.js?code=<yourcode>"></script>
Where <yourcode> will be replaced by the Traceback Code you created in step 1. For example, if your Traceback Code was
dRzABK, then your javascript woudl be : <script defer src="https://t.ixkio.com/s/traceback.js?code=dRzABK"></script>
You can add the code anywhere you choose, for example in the
<head> section or before the end of the <body> section. Traceback has the following flow :
- 1.User scans the NFC tag which directs them to ixkio
- 2.Ixkio handles the authentication check and redirects to your auth page. Ixkio will add a unique Traceback Key into the URL.
- 3.Your page will load the Traceback Javascript which will either :
- 1.Display our Default Display HTML Overlay or
- 2.Display your HTML
- 4.The Traceback Javascript will then make a call to our server to verify the Traceback Key. This will response either as :
- 1.A pass, in which case :
- 1.The Traceback Javascript will simply close our Default Display Overlay or
- 2.The script will hide your HTML and/or
- 3.The script will trigger your javascript function
- 2.A fail, in which case :
- 1.The Trackback Javascript will display a fail message via our Default HTML Overlay or
- 2.The script will redirect instantly to your Traceback Fail URL or
- 3.The script will trigger your javascript function
- 1.If a user attempts to access your auth page directly without any Traceback Key in which case it will trigger a 'No Key' error.
- 2.If a user attempts to re-use a link to your auth page with a Traceback Key, in which case either :
- 1.If the attempt is made quickly (but slower than a normal page hit), then it will trigger an 'Expired Key' error.
- 2.If the attempt is made a substantial time later, then it will trigger an 'Key Not Found' error
- 3.If the user attempts to access the page with an incorrect Traceback Key, then either:
- 1.It will trigger a 'Key Not Found' error, if it looks like it might be a real key or
- 2.It will trigger a 'Key Error' error.
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 Traceback check does not pass, then :
- If a Traceback Fail URL has been entered in your settings, then the user will be redirected to this page
- If a Traceback 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 Traceback Key (when no Key has been provided)
- Traceback Key Error (if the key is of the wrong format)
- Traceback Key Expired (if the key is too old to be used)
- Traceback 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 modified 2mo ago