LogoLogo
  • 🚀DeSo Vision
  • 🪙DeSo Tokenomics
    • No Equity, Just Coins and Code
    • Current DESO Supply
    • Initial DESO Distribution
    • DESO Sinks
    • The BMF: Burn-Maximizing Fee Mechanism
    • Designed for the End-Game
  • 🏛️DeSo Governance
  • ⭐DeSo Tutorial (Build Apps)
  • 🖥️Node Architecture Overview
    • Setup a Node & Frontend Locally
    • Making Your First Changes
  • 📅DeSo Roadmap
  • 🔍DeSo Block Explorer
  • 💸DeSo Wallet
  • 💬DeSo Chat Protocol
  • 👽Openfund
  • 👀Focus
  • 🛠️DeSo Tech Stack
  • 🌐DeSo Applications
  • DeSo Blockchain
    • 1️⃣Bare Metal
    • 2️⃣Scaling Roadmap
    • 3️⃣Content Moderation
    • 4️⃣Infinite-State
    • 5️⃣On-Chain Data
    • 6️⃣Smart Services
    • 7️⃣User Security
  • DeSo Features
    • 1️⃣Associations
    • 2️⃣Creator Coins
    • 3️⃣Feeds & Moderation
    • 4️⃣Social NFTs
    • 5️⃣Social Tipping
  • DeSo Identity
    • 1️⃣Identity: Overview
      • Core Concepts
      • Mobile Integration
    • 2️⃣Identity: iFrame API
      • Overview
      • Endpoints
    • 3️⃣Identity: Window API
      • Overview
      • Endpoints
  • DESO FRONTEND
    • 1️⃣Frontend: Get Started
    • 2️⃣Frontend: React Example
  • DESO BACKEND
    • 1️⃣Backend: Config
      • Onboarding
      • Phone Number Verification
      • Global State
      • Admins
      • Web Security
      • Media
        • Images
        • Videos
      • Hot Feed
      • Selling $DESO
        • Wyre - Buy with USD
        • Buy with BTC
        • Buy with ETH
      • Analytics
      • Emails
      • Supply Monitoring
    • 2️⃣Construct: API
      • Social Transactions API
      • NFT Transactions API
      • Financial Transactions API
      • Derived Keys Transaction API
      • DeSo Tokens Transactions API
      • Associations Transactions API
      • Access Groups API
    • 3️⃣Data: API
      • Admin Endpoints
      • Associations Endpoints
      • DeSo Tokens Endpoints
      • Media Endpoints
      • Miner Endpoints
      • Notification Endpoints
      • NFT Endpoints
      • Social Endpoints
      • Referral Endpoints
      • Tutorial Endpoints
      • Meta Data Endpoints
      • Transaction Spending Limits Endpoints
      • User Endpoints
      • Post Endpoints
      • Messages Endpoints
      • Access Group Endpoints
    • 4️⃣Transactions: API
  • DeSo Exchange Listings
    • 1️⃣Exchange Listing: API
  • DeSo Nodes
    • 2️⃣Node: Setup
    • 3️⃣Node: Staying Up-To-Date
    • 4️⃣Node: FAQ
  • DESO VALIDATORS
    • 1️⃣Run a Validator
  • Openfund
    • What is Openfund?
    • Openfund Tokenomics
    • Openfund Governance
    • Algorithmic Trading
      • The DeSo Python SDK
    • The DeSo Python SDK
      • Getting Help from the Community
      • Creating DeSo Testnet Accounts
      • Debugging Tips and Code Walkthrough
      • Write Blockchain Bots with AI
      • Market-Making Bots
      • Social AI Agents
      • AI-Generating Your Code
    • How Do the Advanced AMMs Work?
  • Focus
    • The Crypto Social Network
    • Next-Generation Token Mechanics
      • Launching Your Token
      • How the Order-Book AMMs Work
    • Crypto-Native Monetization
    • Focus Tokenomics
    • The Social Airdrop
    • Decentralizing Social Media
  • Contact And Media
    • ☀️DeSo Website
    • 📑DeSo Blog
    • 💻DeSo Github
    • 💎DeSo Diamond
    • 🐦DeSo Twitter
    • 📺DeSo YouTube
    • 📬Contact US
    • ⚠️Reporting an Account or Post
  • 中文
    • 什么是DeSo? (What is DeSo?)
    • 愿景 (The Vision)
Powered by GitBook
On this page
  • Messages
  • Storage Access
  • User Credentials

Was this helpful?

  1. DeSo Identity
  2. Identity: iFrame API

Overview

Guide on integrating with the DeSo Identity iframe API

The iframe allows you to perform actions such as signing transactions or encrypting/decrypting messages without user interaction, as is the case in the Identity: Window API.

The iframe is usually entirely invisible to the user.

However, the iframe does need to render on some browsers such as Safari as the user needs to click on the iframe to grant it storage access.

We will explain how to implement this later in the guide.

In order to communicate with the iframe API, you need to include the iframe window HTML component into your app and point it to the https://identity.deso.org/embed URL.

Below is an example component.

We also provided you with an example with CSS styling.

<iframe
  id="identity"
  frameborder="0"
  src="https://identity.deso.org/embed"
  style="height: 100vh; width: 100vw; display: none; position: fixed; 
    z-index: 1000; left: 0; top: 0;"
></iframe>

Take notice of the CSS styling of the iframe component. As mentioned, the iframe is typically invisible to the user. That's why we set the display: none in the CSS style.

We also want the iframe window to be on top of your application and take the entire display, hence the other CSS attributes.

You should modify the z-index attribute to fit your application. In case that we will have to show the iframe to the user, you will set the attribute display: block

For example, document.getElementById("identity.style.display = "block");

Messages

Communication with the iframe context is done through sending postMessage() requests. Similarly, the iframe context will send you responses by sending message events.

When you open the iframe context for the first time, the Identity will send you an initialize message, which requires you to respond.

function uuid() {
    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
        var r = Math.random() * 16 | 0, v = c == 'x' ? r : (r & 0x3 | 0x8);
        return v.toString(16);
    });
}

Here's an example message format that you can send to the Identity iframe.

{
  id: '21e02080-0ef4-4056-a319-a66403f33768',
  service: 'identity',
  method: 'info',
}

Let's take a look at what each of these fields mean:

  • id should be generated to follow the UUID v4 format.

  • service this should always be set to "identity" so that the DeSo Identity Service knows it's supposed to read this message.

You should index requests by id so that you can match them with responses.

Storage Access

Besides initialize, you will need to send an info message to the iframe context.

The DeSo Identity uses local storage and cookies to share information about users between the window and iframe contexts.

However, some browsers such as Safari and Chrome on iOS prevent storing data in such a way without user's explicit permission.

For example, Apple's Intelligent Tracking Prevention (ITP) places strict limitations on cross-domain data storage and access.

This means the Identity iframe must request storage access every time the page reloads.

This can be accomplished by showing the iframe to the user, i.e. setting display: "block", and having the user click on the iframe.

When a user visits a DeSo application in Safari they will see a "Tap anywhere to unlock your wallet" prompt which is a giant button in the iframe. When the user clicks on the button, he will give Identity the required access.

Here's how it looks for the user:

To simplify this process, there's a special API call that you should perform, called info, that will indicate if you should display the iframe window to the user.

The best practice is to send the info message just when you're about to send the first non-initialize request (sign, encrypt, etc.) to the iframe API.

Request

{
  id: '21e02080-0ef4-4056-a319-a66403f33768',
  service: 'identity',
  method: 'info',
}

And here's the response that the iframe will send you:

Response

{
  id: '21e02080-0ef4-4056-a319-a66403f33768',
  service: 'identity',
  payload: {
    browserSupported: true,
    hasCookieAccess: true,
    ​​hasLocalStorageAccess: true,
    ​​hasStorageAccess: true
  },
}

Let's take a look at the above payload fields:

  • browserSupported tells you if DeSo Identity Service is compatible with the user's browser. If it's set to false you should notify the user that Identity won't work for them. Most modern browsers will output true.

  • hasCookieAccess indicates if user browser allows cookies. Identity might store some information in cookies if local storage is unavailable.

  • hasLocalStorageAccess will be true if local storage is available on user's browser.

  • hasStorageAccess indicates if browser has access to storage. If it's set to false you will need to show the iframe window to the user so he can grant access. We will get to this next.

If the info message returns hasStorageAccess: false, your application should make the iframe take over the entire page.

You could do that by setting:

document.getElementById("identity").style.display = "block"

The info message also detects if a user has disabled third party cookies.

Third party cookies are required for Identity to securely sign transactions.

If neither localStorage nor cookies are available, the info returns browserSupported: false and your application should inform the user they will not be able to use Identity to sign or decrypt anything.

When a user clicks "Tap anywhere to unlock your wallet," the iframe will indicate it by sending a storageGranted message.

This request does not expect a response. When your application receives the storageGranted message it can hide the iframe window from the user and the iframe is now ready to receive sign and decrypt, etc. messages.

To hide the iframe, simply call:

document.getElementById("identity").style.display = "none"

storageGranted Message

{
  service: 'identity',
  method: 'storageGranted',
}

User Credentials

The user credentials include three fields, namely encryptedSeedHex, accessLevel, andaccessLevelHmac.

PreviousIdentity: iFrame APINextEndpoints

Last updated 2 years ago

Was this helpful?

This concept has been explained in more detail in the section.

When sending requests to the Identity iframe, you will need to include an id field. The id should be in format.

We recommend using the , or you can also use the following implementation in Vanilla JavaScript:

method this is the API type that you'll request, in this case it's "info" but it could be"sign", "encrypt", etc. as outlined in the section

We recommend looking at the to see how this could be implemented.

In particular, you could trace through the send() method on .

We recommend tracing through the identity/iframe-info-storage-access code snippet in the which implements this communication pattern in Vanilla JavaScript using promises.

If you're familiar with , you can also trace through the , starting with the storageGranted variable on . Here's how the info request looks like:

In order to use the iframe API, you will need to first acquire secure user credentials from the Identity: Window API, through the endpoint.

Which you have to include in all requests to the iframe API. We also explained this concept in the section.

2️⃣
UUID v4
uuid npm package
DeSo Protocol sourcecode
line #257 in src/app/identity.service.ts
examples repository,
RxJS
Deso Protocol code
line #32
iframe UI for granting storage access
Events
Accounts
#api
#log-in