Page: Web client integration – import tokens
2020-11-23 16:11
Web client integration – import tokens
This article covers the integration of Universa Web Client with external systems delivering some Universa-based tokens to the users – e.g. when executing a ICO/Token Sale procedure.
Terms
issuer: some web-service that wants to issue some contracts to its clients (users) identified by email, SMS or like
user: the person which wants to receive a contract to own possession
web or web client or client: Universa's main web interface (v1 or v2)
Process
Suppose we have a service that can send a link to the user to let him or her receive the token. The process is shown on the diagram:
API
To simplify the explanation the suppose some hypothetic SheToken service, having the domain https://she-token.com, wants to issue universa contracts to its clients.
Email/SMS/code input
Issuer must be able to send some unique URL or code to SMS and/or email of its users so they can somehow open the access interface with special integration query that must look somehow like
GET https://mainnetwork.io?iv=1&cb=https://issuer.com/callbacks/somed_codelksu37lsabjwqli7eflgwqb
here parameters are:
iv
: required to 1, integration API protocol versioncb
: the callback that the client calls to get generation data. Can be any,https
is required.
Issuer callback
The Universa web interface saves the initial query parameters and returns to it when initial registration or logging in is performed. The client then calls the cb
url as JSON POST and expects the following answer. (this is a sample data):
{
caption: "She-Token generation",
text: "The She-Token service is ready to generate your 120SHT tokens. Just select or generate the address to receive it to",
action: "select_address",
ok_url: "https://she-token.com/tokens/generate/llkuh345i2384kjkerwq/ok",
cancel_url: "https://she-token.com/tokens/generate/llkuh345i2384kjkerwq/cancel",
check_url: "https://she-token.com/tokens/generate/llkuh345i2384kjkerwq/check",
state: string
}
Parameters are required unless specified otherwise:
caption
: the title of the popup to present to the usertext
: the popup textaction
: must beselect_address
string.ok_url
: URL to call to start token generationcancel_url
: optional. URL to call if the client declines token generationcheck_url
: URL to poll the statusstate
:new
,in_progress
, 'cancelledor
ready`
All callbacks (ok_url
, cancel_url
and check_url
) are called by the client using AJAX calls so the issuer must set up CORS properly. All callbacks are issued with POST action.
States
The initial state should always be new
. Other values are:
state | meaning |
---|---|
new | initial |
in_progress | contract is being generated |
ready | the contract is ready and will be returned on next check |
cancelled | cancel_url was called, generation is no more possible |
Web client callbacks
ok_url
When the user is presented with a popup, the address (of some key) is selected and the "ok" button must be pressed explicitly to
start the generation. When it is done, the web client issues AJAX POST request to ok_url
passing the only parameter
address
: universa address in string form (either short or long) the user has selected
The issuer must return common response with the poll_seconds: int
setting up desired poll time for the web client.
Web client then must check the generation state with check_url
preferably with specified timeout.
check_url
The client issues checks as AJAX POST as many times as needed until it receives the generated token. The issuer returns common response like:
state: state_string, // same as in issuer callback
poll_seconds: int,
base64_contract: base64_string
If poll_seconds
is presented, then token_base64 must not be set. It means that the issuer ask some more time to generate.
If base64_contract
is presented, the generation is done and the issued token is returned.
cancel_url
If specified, the web client sends AJAX POST
request on it when the user selects "cancel" in the popup.
Restore from premature browser page close
It may happen that the user closes the page before the contract is issued and downloaded. To handle this both web client and an issuer must support restore procedure.
Web client restore support
Web client must store the data on the contract being generated in the local storage and cloud of available and continue polling on next page load.
Issuer restore support
Issuer must allow some procedure to redirect to the same link any number of times so the user can re-reqeust the contract. It is
crucial that the callback (cb
) parameter would be the same and the returned data must match what was send the first time except
the state
field, that must reflect the current state of the contract.
Callbacks security
It is highly recommended the issuer selects random sequences to identify "valid" callbacks. The https
protocol is required.
The URL form can be virtually any, different paths, domains, or only differ in query part. The callbacks used int the cb
parameter and its returned data are not restricted to lead to same domain, still, the CORS
must be properly set up on any of them.
Using SMS instead of email
In this case the issuer sends short url which leads to its own website and the code as some clients will not be able to effectively follow long links from SMS. The issuer then checks the code and degenerates data (URLs) for the integration procedure and redirects to the web client.
2-phase verification
If the issuer needs to check the address one more time using user's email or SMS, it could be easily done:
Add information to the issuer callback text that user will receive an extra notification email
After receiving
POST ok_url
send confirmation to user with email/sms including the address to check, ask to confirm it with issuer web servicedo not issue contract until this extra confirmation