Maximillian Laumeister

collectibles.js

NPM version NPM version NPM version

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

  1. Download the latest release from GitHub

  2. Extract the collectibles.js-master folder into your website’s root directory (or wherever you keep your JS libraries)

  3. 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>
     
  4. 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:
    
    
  5. 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:

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.