Skip to content

Latest commit

 

History

History
128 lines (92 loc) · 5.53 KB

README.md

File metadata and controls

128 lines (92 loc) · 5.53 KB
Raw

Nimiq Pop-Up Shop

The Nimiq Pop-Up Shop can turn any static HTML page into a shop using only decentralized (Web3) technology.

Yello! Nimiq is a blockchain that runs in your browser. You can pay anywhere directly from within your browser. No plugins needed. Cool, so now people can pay client-side - but you still need a server to run a shop. :(

Not any more!
Nimiq, web crypto, and IPFS FTW!

The shop is easy to integrate and runs its logic client side - no server needed. :) The data is encrypted and stored on IPFS. Now that the server is gone, you could even deploy your shop itself to IPFS, no problem.

Support this effort by donating NIM to the developers!

Donate NIM

How to use

Checkout the deployed example! As it works in static HTML, here is a dummy shop deployed to GitHub Pages: https://svub.github.io/nimiq-popup-shop/. And to see the orders coming in, copy the content of this file -- that's the private key for the demo store -- and then go to backend/.

How does it work?

Your website, or say, your future web shop is hosted statically somewhere on the web (e.g. netlify.com or via GitHub Pages) and you added Nimiq Checkout buttons to it. Now, your visitors become customers. When they buy something, the order with all the details you need (e-mail, shipping address, you choose) are encoded with your public key and stored as a file on IPFS. The hash of that IPFS file is stored with the transaction when your customer pays you in NIM. And when you as the shop owner want to see the orders and act on them, you just access the statically hosted backend and enter your private key and shop address. It's safe because everything happens client-side, and secure because only the person with the private key can see the orders. Once address and key are entered, all transactions for your shop's address will be fetched from the Nimiq blockchain and then, all the orders will be fetched from IPFS and decrypt using your private key.

But you don't have to fiddle around with all these steps and details, because it's all packed in this lib so you can just add a button and your visitors will become shoppers. :)

Setup your own shop

To create a new shop configuration for your own shop, go to the setup. Or check the section at the bottom about how to run the code and access the setup locally at localhost:3333/backend/setup.html.

During the setup, change the config to what you need and store the file as "nimiq-pop-up-shop-configuration.js".

{
  "name": "Nimiq Pop-Up Shop",
  "address": "NQ07 0000 0000 0000 0000 0000 0000 0000 0000",
  "logo": "https://nimiq.com/favicon-96x96.png",
  "live": false,
  "id": "<automatically generated by the setup process>",
  "publicKey": "<the public key, generated by setup>",
}

Add this JavaScript to your page

  <script src="https://raw.githubusercontent.com/svub/nimiq-popup-shop/master/dist/nimiq-shop.js">

And then use the web compenents anywhere in your shop or website:

  <!--
    Configure your shop! (all callbacks are optional)
    * collectmetadata: 
    *   This callback method will be called by the Nimiq Pop-Up Shop when a customer wants to order.
    *   During the callback, you can open a pop-up and as the user for all additional information that you need 
    *   to fulfil the order, e.g. shipping address - or return false to signal that the user wants to cancel the checkout.
    * onsuccess: Checkout was finished successfully.
    * oncancel: The user has cancelled the checkout process.
    * onerror: Something went wrong, the customer could not finish the checkout process.
    * config: 
    *   URL to your config file (see previous section). 
    *   You don't have to set this if you name the file "nimiq-pop-up-shop-configuration.js" and put it in the same folder.
  -->
  <nimiq-shop collectmetadata="getMetadata" onerror="checkoutError" onsuccess="checkoutSuccess">

    <!-- A first product, price in NIM -->
    <nimiq-shop-checkout-button
      product="Product A"
      price="1.0"
      />

    ...

    <!-- And another product -->
    <nimiq-shop-checkout-button
      product="Product B"
      price="123.0"
      />

  </nimiq-shop>

Contribute

This is an early prototype and there's lots to do and even more possibilities. Check out the issues.

Run example

# install dependencies (only once)
npm install
# run the example
npm run start

Then open your browser at http://localhost:3333.

Tests

Run the tests using a headless Chrome browser:

npm run test

More info about automated testing with headless Chrome: https://developers.google.com/web/updates/2017/06/headless-karma-mocha-chai#run_your_tests

WebComponent approach

Behind the scenes LitElement is used to provide <nimiq-shop-checkout-button> as a web component. LitElement is just "a simple base class for creating fast, lightweight web components". https://lit-element.polymer-project.org/

TypeScript compiler options for LitElement

https://lit-element.polymer-project.org/guide/publish#transpiling-with-typescript