search

blockchain-certificates / cert-web-component

A web component for displaying blockchain certificates.
MIT License
38 stars 38 forks source link

readme

\<blockchain-certificate>

This repository is not being maintained anymore. Please check the <blockcerts-verifier> component if you wish to render & verify a Blockcerts.

This is the easiest way to show a blockchain certificate. Follow the installation instructions below, then use the blockchain-certificate element pointed at the hosted certificate.

<blockchain-certificate href="https://github.com/blockchain-certificates/cert-web-component/blob/master/path/to/your/certificate.json">
</blockchain-certificate

With a valid certificate, you'll get something that follows our community rendering guidelines with minimal effort! It will look something like:

prerendered demo

Using \<blockchain-certificate>

You can use bower to install this web component.

bower install blockchain-certificate --save

At that point, you'll just need to do a few simple things to see the certificate render.

  1. (Optional) Include a polyfill for web components, to add support for older browsers. 
    <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/0.7.22/webcomponents.min.js">
  2. Import the web-component in the header of your html. 
    <link rel="import" href="https://github.com/blockchain-certificates/cert-web-component/blob/master/./blockchain-certificate.html">
  3. Add the \<blockchain-certificate> element and specify the href attribute to the certificate you need to render. 
    <blockchain-certificate href="https://github.com/blockchain-certificates/cert-web-component/blob/master/path/to/your/certificate.json">
</blockchain-certificate

For more detailed documentation on the attributes & a demo, use polymer serve below and go to http://localhost:8080/components/blockchain-certificate/ in order to see polymer's generated docs/demo web application.

Using \<validate-certificate>

A demo of the certificate verifier is available here:

http://localhost:8080/demo/verifier-demo.html

The verifier-demo sample displays and verifies a local Blockchain Certificate (href="https://github.com/blockchain-certificates/cert-web-component/blob/master/sample_signed_cert-valid-1.2.0.json").

<validate-certificate href="https://github.com/blockchain-certificates/cert-web-component/blob/master/sample_signed_cert-valid-1.2.0.json">
  <blockchain-certificate href="https://github.com/blockchain-certificates/cert-web-component/blob/master/sample_signed_cert-valid-1.2.0.json"></blockchain-certificate>
</validate-certificate>

The validate button starts the verification process, and the results are displayed in the web page.

Note that the URL argument may be a URL hosting a Blockcert. This is useful for Blockcerts that are hosted by an issuer, in S3, etc.

Display Guidelines

General Principles

A Blockchain Certificate represents a remarkable achievement on behalf of the recipient. In order to honor that accomplishment, it's important that the display of the certificate be consistent across the various platforms and environments that it might be displayed in.

Standard Open-Source Displays

The fastest way to display a certificate in your application is to use one of the existing displays provided by the open source community. This will ensure a consistent experience for your users across any Blockchain Certificate application with minimal effort on your part.

Here's a list of supported displays:

The <blockchain-certificate> web component

The easiest way to install the standard web components is to use bower. In your project, simply run:

bower install blockchain-certificate --save

Alternatively, you can clone the blockchain-certificate repo and host it independently of your project by running polymer serve in a server environment, like heroku. Note that this approach works best when you can run it on a subdomain, otherwise you'll have to set up Cross-Origin Resource Sharing in order for it to work correctly.

Once you've got the web components as part of your project, there's just a few simple steps to using them. These are also present in the project's README file.

  1. (Optional) Include the web components polyfill to add support for older browsers.
  2. Import the blockchain-certificate.html web component
  3. Use the <blockchain-certificate> element and specify the href path to your certificate.

Let's look at an example.

Step 1: Include the web components polyfill for older browsers. It's important that this be loaded before any other front-end framework you might be using, like Angular or Ember.js.

<script src="https://github.com/blockchain-certificates/cert-web-component/raw/master/components/webcomponentsjs/webcomponents-lite.min.js"></script>

Step 2: Import the blockchain-certificate web component.

<link rel="import" href="https://github.com/blockchain-certificates/cert-web-component/blob/master/components/blockchain-certificate/blockchain-certificate.html">

Step 3: Use the <blockchain-certificate> element in the body of your page.

<blockchain-certificate href="https://github.com/blockchain-certificates/cert-web-component/blob/master/path/to/certificate.json">
</blockchain-certificate>

The <validate-certificate> web component

The <validate-certificate> web component allows for in-browser validation of any hosted certificates. Using this component is easy. After installing or hosting the blockchain-certificate repo, import the validate-certificate web component:

<link rel="import" href="https://github.com/blockchain-certificates/cert-web-component/blob/master/components/blockchain-certificate/validate-certificate.html">

Finally, wrap any <blockchain-certificate> elements in a <validate-certificate> tag.

<validate-certificate>
  <blockchain-certificate href="https://github.com/blockchain-certificates/cert-web-component/blob/master/path/to/certificate.json">
  </blockchain-certificate>
</validate-certificate>

Once that's done, you'll see the same rendered certificate with an associated Validate button. This will perform all of the necessary steps to validate the certificate in the browser.

Caution: The validate-certificate component is only intended to be used in low-risk validation scenarios. It is strongly encouraged that anyone without an established, trusted relationship to the certificate's recipient use an independent verifier installed from a trusted source in order to properly validate the certificate. This prevents someone from writing a fake validator that simply looks like this component, but doesn't do proper validation.

Development

Install the Polymer-CLI

First, make sure you have the Polymer CLI installed. Then run polymer serve to serve your application locally.

Viewing Your Application

$ polymer serve

Building Your Application

$ polymer build

This will create a build/ folder with bundled/ and unbundled/ sub-folders containing a bundled (Vulcanized) and unbundled builds, both run through HTML, CSS, and JS optimizers.

You can serve the built versions by giving polymer serve a folder to serve from:

$ polymer serve build/bundled

Running Tests

$ polymer test

Your application is already set up to be tested via web-component-tester. Run polymer test to run your application's test suite locally.

Contact

Contact us at the Blockcerts community forum.