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: blockFor example,
document.getElementById("identity.style.display = "block");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.When sending requests to the Identity iframe, you will need to include an
id field. The id should be in UUID v4 format.We recommend using the uuid npm package, or you can also use the following implementation in Vanilla JavaScript:
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:
idshould be generated to follow the UUID v4 format.servicethis should always be set to"identity"so that the DeSo Identity Service knows it's supposed to read this message.methodthis 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 api section
You should index requests by
id so that you can match them with responses.In particular, you could trace through the
send() method on line #257 in src/app/identity.service.ts.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:
iframe UI for granting storage access
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.We recommend tracing through the
identity/iframe-info-storage-access code snippet in the examples repository, which implements this communication pattern in Vanilla JavaScript using promises.If you're familiar with RxJS, you can also trace through the Deso Protocol code, starting with the
storageGranted variable on line #32. Here's how the info request looks like:{
id: '21e02080-0ef4-4056-a319-a66403f33768',
service: 'identity',
method: 'info',
}
And here's the response that the iframe will send you:
{
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:
browserSupportedtells you if DeSo Identity Service is compatible with the user's browser. If it's set tofalseyou should notify the user that Identity won't work for them. Most modern browsers will outputtrue.hasCookieAccessindicates if user browser allows cookies. Identity might store some information in cookies if local storage is unavailable.hasLocalStorageAccesswill betrueif local storage is available on user's browser.hasStorageAccessindicates if browser has access to storage. If it's set tofalseyou will need to show theiframewindow 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"
{
service: 'identity',
method: 'storageGranted',
}
In order to use the iframe API, you will need to first acquire secure user credentials from the Identity: Window API, through the log-in endpoint.
The user credentials include three fields, namely
encryptedSeedHex, accessLevel, andaccessLevelHmac.Which you have to include in all requests to the iframe API. We also explained this concept in the Accounts section.
Last modified 7mo ago