README
xdomls
is a localStorage augmentation that uses postMessage
to communicate with a child frame to achieve persistent
storage across domains. it has the ability to automatically sync between the cross browser frame and the top localStorage
object
without any configuration, making native use of localStorage
across different domains frictionless.
getting started
- upload
iframe/build/index.html
to a common domain or public s3 bucket
bundled apps
npm install xdomls
XDOMLS = require('xdomls')
normal pages
including the script client/build/module.min.js
in your page will expose window.XDOMLS
usage
just init the client using the code below and then use localStorage
as you normally would
// simple usage
var client = new XDOMLS('http://yourcdn.com/iframe.html');
client.ready(function(){
client.sync()
})
// additional functionality (can be used with or without sync)
client.ready(function(){
// client will automatically be assigned a persistent unique identifier
console.log('Client ready, session details:',client.SESSION)
// set a persistent value into the frame
client.set('hello-perma','perma-value')
// set a value that expires in 30s
client.set('hello-temp','temp-value',30);
// delete a value
client.del('hello')
// get all values from frame
client.get_all(function(e,r){
console.log(r)
})
})
// instantiation options
new XDOMLS('http://www.taky.com/un/xdomls/iframe/build/index.html',{
// prefix for all keys within the cross browser frame
prefix: 'tracking'
// console logging for client
debug: true,
// console logging for cross browser frame
debug_frame: true,
// shows iframe instead of applying styles to hide it
show_frame: true,
// keys to skip auto-syncing for
sync_ignore_keys: [
'private-key'
],
// sync interval between window.top and cross browser frame
sync_polling_ms: 100,
// cross browser from element id
frame_id: 'persistent-storage',
})
// defaults
{
prefix: 'xd'
debug: false
debug_frame: false
show_frame: false
sync_ignore_keys: []
sync_polling_ms: 100
frame_id: '__xdomls'
}
see example usage in test/example/
tested in
- latest version of all major browsers
- latest version ios/safari
@todo:
- frame location.hash communication mechanism as a
postMessage
fallback
api
|fn|args|description
|-|-|-|
|set
|key,val,[expires_secs=0],[cb]
|set item into cross-domain storage, allows for optional expiration time|
|get
|key,cb
|retrieve item from cross-domain storage|
|get_all
|[simple=true],cb
|retrieve all items from cross-domain storage|
|del
|key,[cb]
|remove item from cross-domain storage|
|clear
|[cb]
|clears all items from xdomls and localStorage (besides the user's session/uuid)|
|get_expired
|[simple=true],cb
|retrieve list of any keys expired this session|
|session
|[refresh=false],[cb]
|get session information, reset session if refresh is true|
|sync
|none|syncs top.localStorage and frame storage automatically|