Not Connected

Ceramic Web Playground

Test the full stack of Ceramic Network components in a web browser.

Technologies

  • Ceramic HTTP Client: Provides access to the Ceramic Network via a remote node running Ceramic (and IPFS).
  • 3ID Connect: Provides authentication to a DID (used by Ceramic) from a blockchain wallet, and stores a link from this blockchain account to your DID in IDX.
  • DataModels: Provides validation for data before it is commited to the Ceramic Network.
  • DID-DataStore: Implements the Identity Index protocol to store and retrieve data associated with a DID from a provided DataModel.

Flight Check

A few things you should see before we continue on...

  1. In the top right corner you should see a little pill that has some random text, this is a concatenated version of your DID. If you want to see the full version in your browser inspector's console you can enter ceramic.did.id to see your full DID.
  2. (optional) We recommend you take a quick look at the technologies we've listed above to get a feel for what Ceramic is capable of.

Variables

  • ceramic, our core client providing access to a testnet node to handle all of our reads & writes.
  • TileDocument, exposes our TileDocument library used to create documents on the Ceramic Network. Once created a document is called a Tile, and the Tile's history is referred to as a "stream".
  • DataStore, our DID-DataStore instance. This is how we'll be interacting with the Identity Index protocol. The BasicProfile DataModel has been preloaded & configured.
Please note, you will not be able to use {import ...} statements as we are not transpling live and you are limited to the technologies provided.

Firing Your First Tile (Sample #1)

The best way to start creating data on the Ceramic Network is to create it. This is going to be a step by step guide to get you started. For this we'll be building some sample blog posts, but you can use any data as long as it's structured as a JSON object.

  1. Let's make sure you're authenticated. In your browser's inspector window open up the 'console' tab & enter ceramic.did.id. You should see something like did:3:.... If you don't refresh the page & re-authenticate your DID.
  2. Let's start by disecting the following command:
    const post1 = await TileDocument.create(ceramic, {
      title:'My first Tile',
      body: 'My first Tile',
      author: ceramic.did.id
    })

    First, TileDocument.create() is the method to create a new tile. It requires two arguments, the ceramic client and the tile data. Now you're ready to run the command and create your tile!
  3. You might have seen in your console that it returned undefined. This is because we're creating, not querying the tile. To see the details about it run post1.content and your browser will show you the content you just created!
  4. That's cool, but what happens when you close your browser and your inspector forgets what we created? That's where the StreamID comes into play. Run post1.id.toString() to see your StreamID. If you're familiar with databases this is similar to your primary key. We can then load a stream by running the following: TileDocument.load(ceramic, post1.id.toString()). You can copy & paste the string from the first command in this step but you don't need to.

That's it! You've now created & loaded your data on Ceramic. You might be wondering how you can load your data without writing down the StreamID or storing it somewhere, that's really where the Identity Index protocol comes in handy.

Working with DID-DataStore (Sample #2)

Now that you've created a tile it's time to work on creating data associated with your personal DID. We've provided the DID-DataStore that has the BasicProfile schema already loaded so all we have to do is use it.

  1. If you haven't worked with Ceramic or the Web Playground in the past take a look at "Firing Your First Tile".
  2. Before we jump into using our DID-DataStore, let's take a look at how it's configured. You can find the source code on GitHub. If you take a look you can see that we're providing a 'publishedModel' to our DID-DataStore, this is a manual way to provide the Schema & Definition to DID-DataStore, you can also use a DataModel that has been published to NPM for this to make it easier.
  3. Now that we've set up the groundwork, we can actually interact with DID-DataStore. So let's start by querying your profile, all you need to do is run: await DataStore.get('basicProfile')
    You might see a JSON response if you've used Self.ID to create a profile in the past, or you might just see undefined. Unless you see an error message you're good to move to the next step.
  4. Retrieving your profile is fine, but what about another persons profile? You can easily query this by providing their DID! Let's take a look at my profile. My DID is: did:3:bafyreihq3gquqeuzblcpckqoanlftg7zp3wivkvg26mzfiwvau45rrepie and with that we can run await DataStore.get('basicProfile', 'did:3:bafyreihq3gquqeuzblcpckqoanlftg7zp3wivkvg26mzfiwvau45rrepie') and retrieve my profile, if you were building your own app ceramic.did.id would reference the DID that is authenticating the Ceramic instance.
  5. So, we've done a lot of querying and no creation. We can almost fix that. First let's talk a bit about best practices. DataStore provides two different utilities for updating a record. The first should ONLY be used when you're creating a Tile for the first time, this being DataStore.set(). If you call this on a record that already has content you will be overwriting all other data in the tile (the stream will maintain it's history though so not all is lost). The second option is the recommended way to create & update data on Ceramic. This is DataStore.merge(), the main difference is that using merge will only update the fields that we are providing.
  6. Finally, we can write to our profile. As mentioned above, we want to be sure to use the right write method and provide good data to use. await DataStore.merge('basicProfile', {name: 'YOUR NAME HERE', description: 'Tell us about yourself!', emoji: '✌🏻' }

That's it! You've now created (or updated) your basicProfile using DID-DataStore, if you take a look at Self.ID you can see your profile has already been updated. Welcome to the world of interoperable data, we're happy to have you here.