3Box Builders Series How to Integrate with Profiles

The Builders Series is a collection of blog posts aimed at helping developers easily build better distributed apps using the 3Box suite of APIs

. This article is the first in the series, and contains everything you need to start adding profiles to your app today. For more information on Profiles, view our Github documentation


3Box Profiles Overview

Why profiles?

3Box Profiles are a quick and easy way to make your decentralized application more social, useable, and interactive with basic social identity that works natively with Ethereum. We provide the infrastructure that makes it easy for distributed application developers to replace user hex addresses with human-readable names, images, descriptions, and other social metadata in their application’s UI.

Why 3Box?

3Box is a distributed data storage and identity network built on IPFS and OrbitDB, where users are always in control of their information. By storing data on 3Box, developers don’t need to operate a centralized backend service to store and manage all of this user information, nor do they need to store it on the blockchain where it’s expensive and exists forever. Rather, 3Box data lives directly with users and is available to be shared across various application front-ends.

Summary of Benefits

Example Integrations

Experience 3Box profiles at any of our partner applications: 3Box Hub , EthStats , NiftyFootball ( coming soon ), Aragon ( coming soon ), Livepeer ( coming soon ), Giveth ( coming soon ), MolochDAO ( coming soon ), MetaMask ( coming soon )

User Experience Demo

Below is a video demonstration of how profiles could integrate natively into an application, in this case — the Livepeer Explorer app. This example is for demonstration purposes only and does not reflect an actual live Livepeer integration. Thanks to Jake Brukhman for letting me use him and CoinFund as example profiles. 🙏

We will reference this Livepeer example for user and application flows, as well as code examples for the remainder of this tutorial.

Get Started Developing with Profiles

Follow these steps to get profiles running smoothly in your app:

📁 Install 3Box.js in your Project

3Box provides a JavaScript client library that allows browser-based web applications to interact with the 3Box data network without requiring the user to install any software. 3Box.js provides the functionality required to perform all of the profile functions below. Let’s get started building! To get started, install 3Box.js in your project:

$ npm install 3box

⚙️ Configure User Profiles

This section describes the application logic and code that should be implemented on the account or profile page of your application.

1. Detect and display default user profile information.

When the user arrives at their profile page, your app should check whether or not they have previously configured their profile for your app. This is indicated by the presence of a defaultProfile setting saved in your app's space. The defaultProfile key functions as a pointer to where profile information for your application should be fetched. This code snippet checks for the defaultProfile setting, stored in your app's space:

const livepeerProfile = await Box.getSpace(
 , 'livepeer')

defaultProfile can be either '3box' , 'livepeer' (i.e. your app’s space), or undefined . Depending on the value, your app should do 1 of 3 things:

2. Ask permission to update their profile.

Regardless of the user’s defaultProfile setting, since they came to their profile page they likely want to create or update their profile, which requires saving data to 3Box. To allow your application to update a user’s 3Box, you will need to ask for the user’s consent then you will need to sync their data. Consent is given by the user signing two consent messages with their web3 wallet: one to access their 3Box and one to access your space. This approval process only needs to be executed once and then it is automatically stored in browser localStorage, so users will only need to sign messages the first time they open their profile page on a new browser. Once the user approves these signature requests in their web3 wallet, their browser can fetch and sync data from the 3Box network. The syncing process must be completed before you can update the user’s 3Box. During this time, you may choose to display a small loading indicator, or block users from making updates to their 3Box profile. This code snippet allows your app to request consent from the user, then sync their data:

const box = await Box.openBox(
const boxSyncPromise = new Promise((resolve, reject) =&gt; box.onSyncDone(resolve))
let livepeerSpace
const spaceSyncPromise = new Promise((resolve, reject) =&gt; {
  livepeerSpace = await box.openSpace('livepeer', { onSyncDone: resolve })
await boxSyncPromise
await spaceSyncPromise

**Note: Steps 3–4 below are only relevant for new users who have no existing defaultProfile setting for your app. At this point, all other users with preconfigured profiles should be able to use and update their profile with no problems.

3. Configure default profile, if not done previously.

Since the user has not previously set up or configured their profile for your app, they should see a blank profile, but you should offer them the option to set one up. After the user clicks “Set up my profile”, you should determine which options to present to the user for setting a default profile in your application: 1) using their existing 3Box profile (if one exists); or 2) setting up a new profile for your application.

Check if existing 3Box profile is present: Call Box.getProfile(<eth-addr>) to check if a user has previously saved profile information (name, image, URL, email) to their general 3Box profile. If they have, display their basic profile info (such as name and image ) in something like a modal, and present the user with the option to use it, or to create a new profile for your app. If the user doesn’t have a pre-existing 3Box profile, you don’t need to provide them with this option, and you can instead just save your app as defaultProfile (option 2 in the code block below), and proceed to Step 4b.

This code snippet describes the data that should be saved to your app’s space, as a result of the user’s selection above:

// Option 1: Set public space data, if 3Box is chosen as default

livepeerSpace.public.set('defaultProfile', '3box')

// OR

// Option 2: Set public space data, if your app is chosen as default

livepeerSpace.public.set('defaultProfile', 'livepeer')

4a. Display profile information, if 3Box is chosen as default.

Display profile with 3Box as default: If the user opts to use their 3Box profile for your app, you should display their 3Box profile information (name, image, URL) on screen using: Box.getProfile(<eth-addres>) .

Edit profile with 3Box as default: If your user has chosen 3Box as default and wishes to edit their profile, it’s advisable to send them to 3box.io to make the updates — since these changes will be reflected across every other application accessed with 3Box, and it might be hard or confusing to communicate that from within your app.

4b. Display profile information, if your app is chosen as default.

Save new app profile data : If users opt for creating a new profile in your app, then you should provide them with an interface to enter their new profile information.

When the user clicks “SAVE”, write this information to their 3Box, in your app’s space:

// Set the public app profile data
livepeerSpace.public.set('defaultProfile', 'livepeer')
livepeerSpace.public.set('name', 'yourname')
const imageObject = [{
  "contentUrl": "
<https: ipfs="" ipfs.infura.io="">
  "cid": {"/":"
livepeerSpace.public.set('image', imageObject)
livepeerSpace.public.set('url', '
  <https: yoursite.com="">

// Set the private app profile data
livepeerSpace.private.set('email', '[email protected]')

Display app profile: When they’re done creating their profile, it should look something like this.

Edit app profile: In this case, it would look the same as the save app profile data step above. You would just re-save the data to your app’s space with new values.

🌈 Display Profiles Throughout Your App

Now that a user has configured their profile for your app, you will want to display it in your app’s UI, making it available to this user and other users on various pages. This section describes the application logic and code that should be implemented on other pages of your app where you wish to display user profiles.

How to Display User Profiles

When your app displays a profile in the UI, you must first check the users’ default profile settings to determine which information to display. This code snippet checks for the defaultProfile setting, stored in your app's space:

const livepeerProfile = await Box.getSpace(
 , 'livepeer')

defaultProfile can be either '3box' , 'livepeer' or undefined . Depending on the value, your app should do 1 of 3 things:

👋 Get in touch

We love to hear about your use cases and we’re happy to answer any questions that arise as you build with our profiles API. Join our Discord at chat.3box.io . View more documentation on Github

Subscribe to our newsletter

Happy building! ⚒️