collectibles.js

collectibles.js is a JavaScript library for adding collectible items to your website. Once the user finds and clicks on all collectible items on your website, they will be greeted with a secret victory page with a URL of your choosing.

Feeling generous? Why not send them to a page with a coupon! Feeling mischievous? Give them the ol’ rick-roll-erooni!

As a demonstration of the library, find and click all 5 demo keys on this web page! For a greater challenge, visit my homepage and find all 5 keys on my main site for the real secret!

Installing collectibles.js

Follow these steps to get collectibles.js running on your own website.

Local Install

Download the latest release from GitHub
Extract the collectibles.js-master folder into your website’s root directory (or wherever you keep your JS libraries)

Embed the library in the <head> section of every page on your website that you want the user to be looking for keys. Make sure you use the exact same initialization options on every page. Here’s the embed code:

 <!-- collectibles.js -->
 <link rel="stylesheet" type="text/css"  href="/collectibles.js-master/dist/collectibles.min.css">
 <script src="/collectibles.js-master/dist/collectibles.min.js" defer></script>
 <script>
     document.addEventListener("DOMContentLoaded", function(e) {
         new CollectiblesJS({
             itemVersion: 1,
             persistent: false,
             numItems: 5
         });
     });
 </script>

Generate your keys using the following utility. The official library supports between 1 and 5 keys - I recommend 5 keys because more keys means more fun to have collecting them! Upon collecting all keys, the user can use them to access the “victory” page on your website that congratulates them for finding all the keys.
Key Generation Utility
Victory Page URL:
Number of Keys:
Hide each key that you generated in a different place on your website. Every page on the same domain running collectibles.js is fair game! Use inline CSS styling of the key div to position it in hard-to-find places on your website!

CDN Install

Instead of downloading and linking collectibles.js locally, you can always use the CDN version. Use the same embed code as up above, but use the CDN tags instead:

<link rel="stylesheet" type="text/css"  href="https://unpkg.com/collectibles.js@0/dist/collectibles.min.css">
<script src="https://unpkg.com/collectibles.js@0/dist/collectibles.min.js"></script>

Themes

Before you collect this last item right here, why not see what the different visual themes look like? We've got keys and coins so far.

Set Theme: Keys Coins

Initialization Options

When initializing collectiblesJS, you may use these arguments:

itemVersion (int) (1) - Start this version number at 1. If you generate new keys (which you would need to do if you wanted to change the victory URL or the total number of keys), be sure to increment this version number, as the previous keys that your users collected will no longer be valid.
persistent (bool) (false) - Set this to false and the user will lose all the keys they found after closing their browser tab. Set this to true and their keys will be saved across browsing sessions. (Under the hood this is the difference between using sessionStorage and localStorage).
numItems (int) (5) - Important! Set this to the total number of keys that you generated using the Key Generation Utility, and that you will hide on your website! Bad things will happen otherwise.
theme (string) (“keys”) - Choose the visual theme of the collectibles. Choices are "keys" and "coins".
keyCollectedCallback (function) (null) - When a user collects a key, this function will be run. It passes one argument - the id number of the key that was collected.

Under The Hood

collectibles.js takes your secret URL and splits it up into n pieces. The “keys” you are given to scatter on your website are real cryptographic keys! When the user finds all the keys, the browser does an n-of-n reconstruction of your secret URL and presents it to the user. This means that nobody can cheese your URL by just viewing source on your web page - they really need to find all the keys!

Persistence across pages is achieved by using the localStorage or sessionStorage browser API, depending on whether you set the “persistent” option when you initialize the CollectibleJS object.

The underlying cryptographic scheme of collectibles.js is Shamir’s Secret Sharing, and the library used for the cryptographic primitives is secrets.js.