Learn how to customise, integrate and connect Matter Impact metrics Elements

This guide explains how to integrate Matter Elements’ Impact metrics for displaying accurate impact metrics:

You can find code for an example implementation on GitHub.

Here’s what you’ll do:

Your design team can have all the flexibility to play around with those specific components. Graphical transformation but also CSS potential is absolutely possible and the only limitations are CSS browser capabilities.

<aside> 🗣 You host and own the source code - you don't need Matter for changes.

</aside>

1️⃣ . Quick start

If you need to quickly test your integration, we give you a quick scenario to copy-paste within your platform to see how it works.

Authorization & Authentication


The API key sample

This is a sample authorization key, that grant access to sample set of portfolios from Matter.

It should be replaced with your API key, delivered by Matter

mk_matter_sample

The portfolio IDs

Each portfolio will have a different ID, and will be delivered by Matter

MATTER_SAMPLE_PORTFOLIO_A
MATTER_SAMPLE_PORTFOLIO_B
MATTER_SAMPLE_PORTFOLIO_C

Adding Embedded Matter Element to your page


To add an embedded Matter Element to your page you need to follow these steps:

  1. Add a script and a stylesheet to your page's <head> like so:

    <script src="<https://elements.thisismatter.com/dist/v1/index.umd.js>"></script>
    <link rel="stylesheet" href="<https://elements.thisismatter.com/dist/v1/index.css>">
    

    This will add a MatterElements object in global scope (window.MatterElements).

    IMPORTANT DISCLAIMER: in the production environment, you MUST NOT use these URLs to import the frontend library script and stylesheet. Please download the bundle from this url and put it into your production server.

  2. Prepare a <div> somewhere in your page and give it an id (position it as it fits you):

    <div id="my-matter-element-container" />
    

    This div will serve as a container for the Element. It should have at least a width specified in any way.

  3. Create a <script> tag (after that <div> or in some kind of "page ready" handler) with the following code:

    // Use your API key here
    const API_KEY = "mk_matter_sample";
    // Fetch the authorization key to use with the API and pass it to the library
    // This should be done only once no matter how many elements you render
    fetch(
      "<https://api.thisismatter.com/elements/v1/auth/user_token>",
      {
        headers: {
          Authorization: `Bearer ${API_KEY}`,
        },
      })
        .then(response => response.json())
        .then(({ token }) => {
          MatterElements.setAuthToken(token);
        })
        .catch(() => {
          alert("Cannot fetch authorization token for Matter Elements API");
        });
    
    // Get the portfolio composition query ready.
    const portfolioComposition = {
      "ids": [{
        "id": "MATTER_wSAMPLE_PORTFOLIO_A",
        "type": "uid",
        "allocation": {
          "amount": 10000,
          "currency": "EUR",
        }
      },{
        "id": "MATTER_SAMPLE_PORTFOLIO_B",
        "type": "uid",
        "allocation": {
          "amount": 10000,
          "currency": "EUR",
        }
      },{
        "id": "MATTER_SAMPLE_PORTFOLIO_C",
        "type": "uid",
        "allocation": {
          "amount": 10000,
          "currency": "EUR",
        }
      }]
    };
    
    // create an instance of Single Impact controller
    const singleImpactElement = MatterElements.singleImpact(
      "co2", // "co2", "waste", "energy", "fossil"
      portfolioComposition,
    );
    
    // assign a container for rendering
    // at least the width of the container should be specified
    // for the Element to be displayed.
    // Some height is necessary to display the loading screen.
    const container = document.getElementById("my-matter-element-container");
    singleImpactElement.render(container);
    
  4. That's it! 🤘

Getting API Matter Element to your page