Developer Resources - Remote Signup
Revision 1.07 - updated 2012.05.30
Description
Remote Signup can be used to enable the user of a third party site to sign up for a new bambuser account and tie it to his/her account on the third party site, without leaving the context of the third party site.
The implementation is utilizing an iframe fetched from Bambuser, which allows the third party site to give the end user an appearence of being on the third party site during the entire process. This also means Bambuser can improve functionality, generally without requiring work efforts from the third party site developers.
Remote Signup is only available to selected partners. If you would like to apply, use the contact form and include a brief description of your site or project including a motivation why your site qualifies as a Remote Signup site.
Flow example
The screenshots below illustrates what the signup process looks like. The iframe can be embedded into your site and triggered in any way you like (as a popup or overlay, in a sidebar of your site, on a dedicated page, inserted dynamically with javascript or on page reload, etc...), hence the final look and feel is up to you.
When the accounts are linked, the user has access to the most important Bambuser tools from within the iframe. If the signup process has been completed, the user is always returned directly to this screen when you present the Remote Signup iframe to them.
Demonstration
A demo of remote signup is available at http://bambuser.com/remote-signup/1.0/test
The demo site is simulating a social networking site. The demo site itself is a bit rough around the edges, but it demonstrates the concept.
The first page allows you to log in by selecting your usertoken. At the same time it displays what data will be used in the Iframe request later on.
The second page takes you to you fictive profile page. To the left is your name, avatar and all the other stuff. To the right is a button which allows you to sign up for bambuser and tie your bambuser account to the social networking site. How you design this button or link is up to you!
The third page is a refresh of the profile page, this time with the Remote Signup Iframe loaded. On your own site you can of course put it on whatever page you like and even load it with JavaScript if you fancy (as long as you use the correct Iframe params)
At all times you can see the linkage and unlinkage requests made by Bambuser to the third party site, in the log view at the bottom of the page.
Prerequisites
To enable Bambuser remote signup on your site, the following requirements need to be met:
- You need to be accepted as a partner site.
- You need to give Bambuser a service callback URL at your end which receives confirmation from the Bambuser service when a user has successfully signed up or authenticated using his existing account.
- You need an identifier for your site specified by Bambuser.
- You need a secret key specified by Bambuser.
Example
| callback_url | http://yoursite.com/services/bambuser-remote-signup.php |
|---|---|
| id | yoursite |
| secret_key | de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3 |
Iframe request
<iframe> attributes
| src | http://bambuser.com/remote-signup/1.0/iframe?[PARAMETERS] |
|---|---|
| width | 320 pixels |
| height | 500 pixels |
| scrolling | auto |
Iframe url [PARAMETERS]
| id | Your website's identifier as defined by Bambuser |
|---|---|
| usertoken | The user token used on the third party site to represent the user, typically a user name or user id. Needs to be escaped properly if it contains spaces or non-alphanumeric characters. |
| ts | Timestamp, given as seconds since January 1 1970 (UTC) - used as a security measure,
to invalidate the key a reasonable number of minutes after the iframe is generated.
http://en.wikipedia.org/wiki/Unix_time |
| key | A SHA-1-hash generated from your secret key, the user token and the current unix timestamp combined.
SHA1( secret_key + usertoken + ts )
|
| suggested_username (optional) | Allows the third party site to prepopulate the signup form with a suggested Bambuser username. |
| suggested_email (optional) | Allows the third party site to prepopulate the signup form with the user's email address. If you use this feature, make sure you have the user's permission to relay the address to Bambuser! |
| action (optional) | Allows the third party site to initiate misc alternative workflows. See "Additional iframe actions" for details. |
| return_url (depends on action parameter) | See "Additional iframe actions" for details. |
Example
id=yoursite&usertoken=someusername&ts=1219740539&key=4f0034d8a8105f34d9de1090a4bec5875f5d88f2
" width="320" height="500" scrolling="auto"> </iframe>
Linkage request
When a user completes the remote signup process, Bambuser ties the usertoken you have specified and your website id, to the created or selected Bambuser account.
Bambuser then queues a confirmation task, which when executed makes a HTTP POST request to the callback you have specified (in the above example: http://yoursite.com/services/bambuser-remote-signup.php). The request is usually generated within seconds but Bambuser reserves the right to keep the job in queue for a short period of time if needed.
Your callback is expected to return a HTTP 200 status code (http://en.wikipedia.org/wiki/List_of_HTTP_status_codes). If any other response is recieved, or your callback is unavailable, Bambuser puts the task back in queue with a low priority and makes a limited number of retries.
Linkage confirmation HTTP POST parameters
| command | String | link |
|---|---|---|
| username | String | The Bambuser username. Might contain any UTF-8 characters. |
| usertoken | String | The user token you have specified as "user id at your end" when loading the Iframe. |
| ts | Integer | The timestamp used when generating the key for the linkage request. |
| key | String | A SHA-1-hash generated from your secret key, the command, the bambuser username, the user token
and the current unix timestamp combined. NOT the same key used in the iframe request.
SHA1( secret_key + command + username + usertoken + ts )
We strongly recommend that your callback implementation requires a valid key. Whe also recommend that you do not accept keys based on a timestamp older than 24 hours. |
Unlinkage request
The user has removed the link from Bambuser to the 3:rd party account. Allows the 3:rd party site to take appropriate action.
Works like the linkage request, except the command is changed to 'unlink'.
Unlinkage confirmation HTTP POST parameters
| command | String | unlink |
|---|---|---|
| username | String | The Bambuser username. Might contain any UTF-8 characters. |
| usertoken | String | The user token you have specified as "user id at your end" when loading the Iframe. |
| ts | Integer | The timestamp used when generating the key for the linkage request. |
| key | String | A SHA-1-hash generated from your secret key, the command, the bambuser username, the user token
and the current unix timestamp combined. NOT the same key used in the iframe request.
SHA1( secret_key + command + username + usertoken + ts )
We strongly recommend that your callback implementation requires a valid key. Whe also recommend that you do not accept keys based on a timestamp older than 24 hours. |
Additional iframe actions
The third party site can initiate actions outside of the normal workflow within the iframe. These are triggered by embedding the iframe (see above) and setting the "action" url parameter to the desired action. Optionally, the "return_url" parameter can be set, which allows you to send the user to an url of your choice when the action is completed (if applicable).
unlink
The unlink action promts the user to unlink the Bambuser account from the third party site account. A dialog informs the user that the Bambuser account in question and all its broadcasts will continue to exist. User interaction is required.
When user submits the unlink form, Bambuser's servers tries to make an unlinkage request (see above) to the third party service's specified callback. If the service returns status code 200, unlinking is done at Bambuser's end. If another status code than 200 is returned, unlinking is not done.
The user is then returned to the given return url (or to a status message inside the iframe if no return url has been specified). Hence, when the third party receives the return url request from the user, the unlinkage request is guaranteed to either have been processed or to have failed.
