JavaScript SDK Design Guide
Introduction
This guide provides an introduction to develop a JavaScript SDK.
The best one sentence to describe an SDK is: “The SDK is the connection bridging the gap between users and the (browser) machine.”
By using this guide, the SDK will be able to run in browsers, desktop, mobile web and various other platforms capable of running JavaScript.
The target audience of this writeup excludes non-browser environments such as hardware, embedded and Node.js.
Suggest improvements by editing, or drop suggestions on the issue list. I owe you a beer :beers:
READ IT
ONLINE
Content
- What is an SDK
- Design Philosophy
- Scope
- Include the SDK
- SDK Versioning
- Changelog Document
- Namespace
- Storage Mechanism
- Event
- Request
- Component of URI
- Debugging
- Tips and Tricks
- Piggyback
- Page Visibility API
- Document Referrer
- Console Logs Polyfill
- EncodeURI or EncodeURIComponent
- YOU MIGHT NOT NEED JQUERY
- You Don’t Need jQuery
- Load Script with Callback
- Once Function
- Pixel Ratio Density
- Get Style Value
- Check if Element in Viewport
- Check if Element is Visible
- Get Viewport Size
- User Tracking
- Opt Out
- WTF
- Template
- Book to Read
- Contributors
What is an SDK
This question is pretty ubiquitous, but here it is again.
“Short for software development kit, a programming package that enables a programmer to develop applications for a specific platform. Typically an SDK includes one or more APIs, programming tools, and documentation.” - webopedia
Design Philosophy
Depending on the purpose of SDK’s service and usage — common shared traits are, but not limited to be native, short, fast, clean, readable and testable.
The widely adopted good practice, is to write SDK with vanilla JavaScript. Languages compiling to JavaScript such as LiveScript, CoffeeScript, TypeScript and others are not recommended.
It is also recommended not to use libraries such as jQuery in SDK development. The exception is of course when it is really important. There are also other jQuery-like libraries, zepto.js etc to choose from, for the DOM manipulation purposes.
In event of HTTP ajax request requirements — there are native equivalent such as window.fetch
. It is light-weight, supported in ever growing platforms.
Backward compatibility is paramount. Every new SDK version released should be enabled with support of previous older versions. Likewise, current version should be designed to support future SDK versions. This is referred to as Forward compatibility.
Moreover, a good Documentation, well commented code, a healthy unit test coverage, as well as end-to-end (user) scenario are key to the success of SDK.
Scope
Based on the book Third-Party JavaScript
Three use cases worth considering while designing a JavaScript SDK:
- Embedded widgets - Small interactive applications embedded on the publisher’s web page (Disqus, Google Maps, Facebook Widget)
- Analytics and metrics - For gathering intelligence about visitors and how they interact with the publisher’s website (GA, Flurry, Mixpanel)
- Web service API wrappers - For developing client-side applications that communicate with external web services. (Facebook Graph API)
Suggest a case in which the use of an SDK in JavaScript environment is deemed important.
Include the SDK
To include the SDK in a user-facing environment, It is a good practice to use Asynchronous Syntax to load the scripts.
This helps to optimize the user experience on the website that are using the SDK. This approach reduces chances of the SDK library interfering with the hosting website.
Asynchronous Syntax
<script>
(function () {
var s = document.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'http://<DOMAIN>.com/sdk.js';
var x = document.getElementsByTagName('script')[0];
x.parentNode.insertBefore(s, x);
})();
</script>
The async
syntax is used when targetting modern browsers.
<script async src="http://<DOMAIN>.com/sdk.js"></script>
Traditional Syntax
<script type="text/javascript" src="http://<DOMAIN>.com/sdk.js"></script>
Comparison
Here’s the simple graph to show the difference between Asynchronous and Traditional Syntax.
Asynchronous:
|----A-----|
|-----B-----------|
|-------C------|
Synchronous:
|----A-----||-----B-----------||-------C------|
Asynchronous and deferred JavaScript execution explained
https://developers.google.com/speed/docs/insights/BlockingJS
It is good practice to avoid, or minimize, the use of blocking JavaScript, especially external scripts that must be fetched before they can be executed. Scripts that are necessary to render page content can be inlined to avoid extra network requests, however the inlined content needs to be small and must execute quickly (non-blocking fashion) to deliver good performance. Scripts that are not critical to initial render should be made asynchronous or deferred until after the first render.
Problem of Asynchronous
When using an Asynchronous approach, It is ill-advised to execute SDK initialization functions before all libraries are loaded, parsed and executed in the hosting page.
Consider the following snippet as a visual example to the previous statement:
<script>
(function () {
var s = document.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'http://<DOMAIN>.com/sdk.js';
var x = document.getElementsByTagName('script')[0];
x.parentNode.insertBefore(s, x);
})();
// execute your script immediately here
SDKName('some arguments');
</script>
The end result of such initialization will lead to bugs.
The SDKName()
function, undefined at this point, executes before it becomes available in the environment’s global variable. The script is not loaded yet.
To make it work, some tricks are necessary to make sure the script executes successfully. The event will (need to) be stored in the SDKName.q
queue array. The SDK should be able to handle and execute the SDKName.q
event and initialize the SDKName
namespace.
The following snippet depicts the statement in previous paragraph.
<script>
(function () {
// add a queue event here
SDKName = SDKName || function () {
(SDKName.q = SDKName.q || []).push(arguments);
};
var s = document.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'http://<DOMAIN>.com/sdk.js';
var x = document.getElementsByTagName('script')[0];
x.parentNode.insertBefore(s, x);
})();
// execute your script immediately here
SDKName('some arguments');
</script>
Or using [].push
<script>
(function () {
// add a queue event here
SDKName = window.SDKName || (window.SDKName = []);
var s = document.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'http://<DOMAIN>.com/sdk.js';
var x = document.getElementsByTagName('script')[0];
x.parentNode.insertBefore(s, x);
})();
// execute your script immediately here
SDKName.push(['some arguments']);
</script>
Others
There are other different ways to include a script
Import in ES2015
import "your-sdk";
Modular include a Script
There is full source code — and this awesome tutorial “Loading JavaScript Modules“ may help for in-depth understanding of concepts discussed above.
module('sdk.js',['sdk-track.js', 'sdk-beacon.js'],function(track, beacon) {
// sdk definitions, split into local and global/exported definitions
// local definitions
// exports
});
// you should contain this "module" method
(function () {
var modules = {}; // private record of module data
// modules are functions with additional information
function module(name,imports,mod) {
// record module information
window.console.log('found module '+name);
modules[name] = {name:name, imports: imports, mod: mod};
// trigger loading of import dependencies
for (var imp in imports) loadModule(imports[imp]);
// check whether this was the last module to be loaded
// in a given dependency group
loadedModule(name);
}
// function loadModule
// function loadedModule
window.module = module;
})();
SDK Versioning
It is not a good practice to use one of the following versioning styles:
brand-v<timestamp>.js
brand-v<datetime>.js
brand-v1-v2.js
,
The reason is that it becomes confusing to track the lastest version. Therefore, previous styling does not help developers who use the SDK.
It is however a good practice to use Semantic Versioning, also known as SemVer, when versioning SDKs.
It has three main parts, each corresponding to importance of a release: “MAJOR.MINOR.PATCH”.
Version in v1.0.0
v1.5.0
v2.0.0
is easier to trace and track in changelog documentation, for instance.
Depending on service design, some of the ways SDK can be distributed (or tracked) by version are the following:
- Using Query String path —
http://<DOMAIN>.com/sdk.js?v=1.0.0
- Using the Folder Naming —
http://<DOMAIN>.com/v1.0.0/sdk.js
- Using hostname (subdomain) —
http://v1.<DOMAIN>.com/sdk.js
Depending on Use Case, there are other environment dependent forms that are commonly advised to use:
- In
stable
versionhttp://<DOMAIN>.com/sdk-stable.js
- In
unstable
versionhttp://<DOMAIN>.com/sdk-unstable.js
- In
alpha
versionhttp://<DOMAIN>.com/sdk-alpha.js
- In
latest
versionhttp://<DOMAIN>.com/sdk-latest.js
- In
experimental
versionhttp://<DOMAIN>.com/sdk-experimental.js
Reading suggestion: *Why use SemVer?* on
npm
blog.
Changelog Document
It’s hard to notice when an SDK has updates (or is upgraded) when no announcement has been issued. It’s good practice to write a Changelog to document major, minor and even bug-fix changes. Tracking changes in SDK APIs deliver good developer experience. - Keep a Changelog (Github Repo)
Each version should have:
[Added] for new features.
[Changed] for changes in existing functionality.
[Deprecated] for soon-to-be removed features.
[Removed] for now removed features.
[Fixed] for any bug fixes.
[Security] in case of vulnerabilities.
In addition, commit-message-emoji uses an emoji to explain the commit’s changes itself. Find the best suitable format or changelog generator tool for your project.
Namespace
To avoid collision with other libraries, it is better to define no more than one global SDK namespace. The naming should also avoid using the commonly used words and catch-phrases as namespaces.
As a quick example, SDK playground can well use (function () { ... })()
or ES6 Blocks { ... }
to wrap all sources.
This is an increasingly common practice found in many popular JavaScript libraries such as (jQuery, Node.js, etc.). This technique creates a closure around the entire contents of the file which, perhaps most importantly, creates a private namespace and thereby helps avoid potential name clashes between different JavaScript modules and libraries. #
To avoid namespace collision
From Google Analytics, define the namespace by changing the value ga
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
From OpenX experience, support a parameter to request the namespace.
<script src="http://your_domain/sdk?namespace=yourcompany"></script>
Storage Mechanism
Cookie
The domain scope of using cookies is quite complex while involving the subdomain
and path
.
For path=/
,
there is a cookie part first=value1
in domain http://github.com
,
and another cookie second=value2
in domain http://sub.github.com
http://github.com | http://sub.github.com | |
---|---|---|
first=value1 | ✓ | ✓ |
second=value2 | ✘ | ✓ |
There is a cookie first=value1
in domain http://github.com
,
cookie second=value2
in domain path http://github.com/path1
and cookie third=value3
in domain http://sub.github.com
,
http://github.com | http://github.com/path1 | http://sub.github.com | |
---|---|---|---|
first=value1 | ✓ | ✓ | ✓ |
second=value2 | ✘ | ✓ | ✘ |
third=value3 | ✘ | ✘ | ✓ |
Check Cookie Writable
Given a domain (Default as current hostname), check whether the cookie is writable.
var checkCookieWritable = function(domain) {
try {
// Create cookie
document.cookie = 'cookietest=1' + (domain ? '; domain=' + domain : '');
var ret = document.cookie.indexOf('cookietest=') != -1;
// Delete cookie
document.cookie = 'cookietest=1; expires=Thu, 01-Jan-1970 00:00:01 GMT' + (domain ? '; domain=' + domain : '');
return ret;
} catch (e) {
return false;
}
};
Check Third-Party Cookie Writable
It’s impossible to check only using client-side JavaScript, but a server can help to achieve just that.
Write/Read/Remove Cookie Code
Code snippet for write/read/remove cookie script.
var cookie = {
write: function(name, value, days, domain, path) {
var date = new Date();
days = days || 730; // two years
path = path || '/';
date.setTime(date.getTime() + (days * 24 * 60 * 60 * 1000));
var expires = '; expires=' + date.toGMTString();
var cookieValue = name + '=' + value + expires + '; path=' + path;
if (domain) {
cookieValue += '; domain=' + domain;
}
document.cookie = cookieValue;
},
read: function(name) {
var allCookie = '' + document.cookie;
var index = allCookie.indexOf(name);
if (name === undefined || name === '' || index === -1) return '';
var ind1 = allCookie.indexOf(';', index);
if (ind1 == -1) ind1 = allCookie.length;
return unescape(allCookie.substring(index + name.length + 1, ind1));
},
remove: function(name) {
if (this.read(name)) {
this.write(name, '', -1, '/');
}
}
};
Session
It’s important to know that in JavaScript it is not possible to write a Session. That is the server responsibility. The server-side team should implement Session management related Use Cases.
A page session lasts for as long as the browser is open and survives over page reloads and restores. Opening a page in a new tab or window will cause a new session to be initiated.
LocalStorage
Stores data with no expiration date, storage limit is far larger (at least 5MB) and information is never transferred to the server.
It’s good to know that each localStorage from http
and https
in the same domain aren’t shared.
Creating an iframe inside a website and using postMessage
to pass the value to others.
Check LocalStorage Writable
window.localStorage is not supported by all browsers, the SDK should check if it’s available before using it.
var testCanLocalStorage = function() {
var mod = 'modernizr';
try {
localStorage.setItem(mod, mod);
localStorage.removeItem(mod);
return true;
} catch (e) {
return false;
}
};
Session Storage
Stores data for one session (data is lost when the tab is closed).
Check SessionStorage Writable
var checkCanSessionStorage = function() {
var mod = 'modernizr';
try {
sessionStorage.setItem(mod, mod);
sessionStorage.removeItem(mod);
return true;
} catch (e) {
return false;
}
}
Event
In client browser, there are events load
unload
on
off
bind
…. Here’s some polyfills for you to handle all different platforms.
Document Ready
Please do make sure that the entire page is finished loading (ready) before starting execution of the SDK functions.
// handle IE8+
function ready (fn) {
if (document.readyState != 'loading') {
fn();
} else if (window.addEventListener) {
// window.addEventListener('load', fn);
window.addEventListener('DOMContentLoaded', fn);
} else {
window.attachEvent('onreadystatechange', function() {
if (document.readyState != 'loading')
fn();
});
}
}
DOMContentLoaded - fired when the document has been completely loaded and parsed, without waiting for stylesheets, images, and subframes to finish loading
load event can be used to detect a fully-loaded page
Information from JS Tip - https://github.com/loverajoel/jstips/blob/master/_posts/en/javascript/2016-02-15-detect-document-ready-in-pure-js.md
Message Event
It’s about the cross-origin communication between iframe and window, read the API documentation.
// in the iframe
parent.postMessage("Hello"); // string
// ==========================================
// in the iframe's parent
// Create IE + others compatible event handler
var eventMethod = window.addEventListener ? "addEventListener" : "attachEvent";
var eventer = window[eventMethod];
var messageEvent = eventMethod == "attachEvent" ? "onmessage" : "message";
// Listen to message from child window
eventer(messageEvent,function(e) {
// e.origin , check the message origin
console.log('parent received message!: ',e.data);
},false);
The Post message data should be String, for more advanced use in JSON, use JSON String. Although the modern browsers do support Structured Clone Algorithm on the parameter, not all browsers do.
Orientation Change
Detect device orientation change
window.addEventListener('orientationchange', fn);
Get Orientation Rotate Degree
window.orientation; // => 90, -90, 0
Screen portrait-primary, portrait-secondary, landscape-primary, landscape-secondary (Experimental)
// https://developer.mozilla.org/en-US/docs/Web/API/Screen/orientation
var orientation = screen.orientation || screen.mozOrientation || screen.msOrientation;
Disable Scroll
In web page, use CSS style overflow: hidden
, in some mobile webs, this CSS doesn’t work, use JavaScript event.
document.addEventListener('touchstart', function(e){ e.preventDefault(); });
// or
document.body.addEventListener('touchstart', function(e){ e.preventDefault(); });
// use move if you need some touch event
document.addEventListener('touchmove', function(e){ e.preventDefault(); });
// target modern browser
document.addEventListener('touchmove', function(e){ e.preventDefault(); }, { passive: false });
Request
The communication between our SDK and Server is using Ajax Request. Most common use cases leverage jQuery’s ajax http request to communicate with the Server. The good news is that there is an even better solution to achieve that.
Image Beacon
Using the Image Beacon to ask the browser to perform a GET method request
to get an Image.
Ones should always remember to add timestamp (Cache Buster) to prevent caching in browser.
(new Image()).src = 'http://<DOMAIN>.com/collect?id=1111';
Some notice for GET Query String, there is the limit of length which is 2048 (Basically it depends on different browsers and server). The following trick helps to handle the case of exceeded length limit.
if (length > 2048) {
// do Multiple Post (form)
} else {
// do Image Beacon
}
There are well-known problems using encodeURI
or encodeURIComponent
. However, it is better to understand how these two approaches work. Reading details below.
For the image load success/error callback
var img = new Image();
img.src = 'http://<DOMAIN>.com/collect?id=1111';
img.onload = successCallback;
img.onerror = errorCallback;
Single Post
it is possible to use the native form element POST method to send a key value.
var form = document.createElement('form');
var input = document.createElement('input');
form.style.display = 'none';
form.setAttribute('method', 'POST');
form.setAttribute('action', 'http://<DOMAIN>.com/track');
input.name = 'username';
input.value = 'attacker';
form.appendChild(input);
document.getElementsByTagName('body')[0].appendChild(form);
form.submit();
Multiple Posts
The Service is often complex, especially when needing to send more data through a POST method.
function requestWithoutAjax( url, params, method ){
params = params || {};
method = method || "post";
// function to remove the iframe
var removeIframe = function( iframe ){
iframe.parentElement.removeChild(iframe);
};
// make a iframe...
var iframe = document.createElement('iframe');
iframe.style.display = 'none';
iframe.onload = function(){
var iframeDoc = this.contentWindow.document;
// Make a invisible form
var form = iframeDoc.createElement('form');
form.method = method;
form.action = url;
iframeDoc.body.appendChild(form);
// pass the parameters
for( var name in params ){
var input = iframeDoc.createElement('input');
input.type = 'hidden';
input.name = name;
input.value = params[name];
form.appendChild(input);
}
form.submit();
// remove the iframe
setTimeout( function(){
removeIframe(iframe);
}, 500);
};
document.body.appendChild(iframe);
}
requestWithoutAjax('url/to', { id: 2, price: 2.5, lastname: 'Gamez'});
Iframe
Iframe embedded in html can always be used to cover the use case of generating content within the page.
var iframe = document.createElement('iframe');
var body = document.getElementsByTagName('body')[0];
iframe.style.display = 'none';
iframe.src = 'http://<DOMAIN>.com/page';
iframe.onreadystatechange = function () {
if (iframe.readyState !== 'complete') {
return;
}
};
iframe.onload = loadCallback;
body.appendChild(iframe);
Remove extra margin from INSIDE an iframe
<iframe src="..."
marginwidth="0"
marginheight="0"
hspace="0"
vspace="0"
frameborder="0"
scrolling="no"></iframe>
Putting html content into an iframe
<iframe id="iframe"></iframe>
<script>
var html_string= "content <script>alert(location.href);</script>";
document.getElementById('iframe').src = "data:text/html;charset=utf-8," + escape(html_string);
// alert data:text/html;charset=utf-8.....
// access cookie get ERROR
var doc = document.getElementById('iframe').contentWindow.document;
doc.open();
doc.write('<body>Test<script>alert(location.href);</script></body>');
doc.close();
// alert "top window url"
var iframe = document.createElement('iframe');
iframe.src = 'javascript:;\'' + encodeURI('<html><body><script>alert(location.href);</body></html>') + '\'';
// iframe.src = 'javascript:;"' + encodeURI((html_tag).replace(/\"/g, '\\\"')) + '"';
document.body.appendChild(iframe);
// alert "about:blank"
</script>
Script jsonp
This is the case where your server needs to send a JavaScript response
and let the client browser execute it.
Just include the JS script link.
(function () {
var s = document.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = '/yourscript?some=parameter&callback=jsonpCallback';
var x = document.getElementsByTagName('script')[0];
x.parentNode.insertBefore(s, x);
})();
To learn more about jsonp
- JSONP only works in GET HTTP requests.
- JSONP lacks error handling, means you cannot detect cases in response status code 404, 500 and so on.
- JSONP requests are always asynchronous.
- Beware of CSRF attack.
- Cross domain communication. Script response side (server-side) don’t need to care about CORS.
Navigator.sendBeacon()
Look at the documentation.
This method addresses the needs of analytics and diagnostics code that typically attempt to send data to a web server prior to the unloading of the document. Sending the data any sooner may result in a missed opportunity to gather data. However, ensuring that the data has been sent during the unloading of a document is something that has traditionally been difficult for developers.
Send POST beacon through the API. It’s cool.
navigator.sendBeacon("/log", analyticsData);
XMLHttpRequest
Writing XMLHttpRequest is not a good idea. I assume that you don’t want to waste time on battling with IE or other browsers. Here are some polyfills or code you can try:
- window.fetch - A window.fetch JavaScript polyfill. (check also ky)
- got - Simplified HTTP/HTTPS requests
- microjs - list of ajax lib
- more
Fragment Identifier
Also known as hash mark #
. Remember that requests with hash mark at the end are not passed within http requests.
For example, you are in the page http://github.com/awesome#hueitan
// Sending a request with a parameter url which contains current url
(new Image()).src = 'http://yourrequest.com?url=http://github.com/awesome#hueitan';
// actual request will be without #
(new Image()).src = 'http://yourrequest.com?url=http://github.com/awesome';
// Solution, encodeURIComponent(url):
(new Image()).src = 'http://yourrequest.com?url=' + encodeURIComponent('http://github.com/awesome#hueitan');
Maximum Number of Connections
Check the maximum number of the browser’s request connections. browserscope
Component of URI
It’s important to know if the SDK needs to parse the location url.
authority
__________|_________
/ \
userinfo host resource
__|___ ___|___ __________|___________
/ \ / \ / \
username password hostname port path & segment query fragment
__|___ __|__ ______|______ | __________|_________ ____|____ |
/ \ / \ / \ / \ / \ / \ / \
foo://username:password@www.example.com:123/hello/world/there.html?name=ferret#foo
\_/ \ / \ \ / \__________/ \ \__/
| | \ | | \ |
scheme subdomain \ tld directory \ suffix
\____/ \___/
| |
domain filename
Parsing URI
Here’s a simple way using the native URL() Interface but it’s not supported by all browsers. It is also not a standard yet.
var parser = new URL('http://github.com/hueitan');
parser.hostname; // => "github.com"
The DOM ‘s createElement('a')
can be used in browsers that don’t have the URL()
Interface yet.
var parser = document.createElement('a');
parser.href = "http://github.com/hueitan";
parser.hostname; // => "github.com"
Debugging
Simulating Multiple Domains
To simulate multiple domains, there is no need to register different domain names. Editing operating system’s hosts file can do the trick.
$ sudo vim /etc/hosts
Add the following entries
# refer to localhost
127.0.0.1 publisher.net
127.0.0.1 sdk.net
Every website URL becomes accessible via http://publisher.net
and http://sdk.net
Developer Tools
Browsers come with debugging tools specific to every vendor. Obviously, these tools can be used to debug SDK JavaScript code - Chrome Developer Tools
Safari Developer Tools
Firebug
. Developer tools also shortened as DevTools.
The DevTools provide web developers deep access into the internals of the browser and their web application. Use the DevTools to efficiently track down layout issues, set JavaScript breakpoints, and get insights for code optimization.
Simulate a slower network connection
The network connection of the computer that you use to build sites is probably faster than the network connections of the mobile devices of your users. By throttling the page you can get a better idea of how long a page takes to load on a mobile device. — https://developers.google.com/web/tools/chrome-devtools/network#throttle
Console Logs
For testing expected output text and other general debugging, Console Logs
can be used through the browser API console.log()
. There are various typeways to format and output messages. There is more on this discussed at this link: Console API.
Debugging Proxy
Debugging proxy gives us a hand on testing SDK in development. Some of the areas covered are:
- Debugging traffic
- modify cookies
- Inspecting headers
- Verifying the cache
- Editing http request/response
- SSL Proxying
- Debugging Ajax and more.
Here’s some software you can try
BrowserSync
BrowserSync makes it easy to tweak and test faster by synchronizing file changes and interactions across multiple devices. It’s wicked-fast and totally free.
It really helps a lot to test the SDK across mutliple devices. Totally worth a try =)
Debugging Node.js Apps
To debug SDK scripts in Chrome Developer Tools. (Node.js v6.3.0+ required)
$ node --inspect-brk [script.js]
Tips and Tricks
Piggyback
Sometimes, including all the SDK source code is not required in some use cases. That is the case of a simple 1x1 pixel request – For example: make a request when someone lands on thank you (last) page. In such a scenario, the developer may include an image file with a the (url) link, as explained in the following snippet.
<img height="1" width="1" alt="" style="display:none" src="https://yourUrlLink.com/t?timestamp=1234567890&type=page1¤cy=USD&noscript=1" />
Page Visibility API
Sometimes, the SDK wants to detect if a user has a particular page in focus. These polyfills visibly.js and visibilityjs may help achieve just that.
Document Referrer
The document.referrer
can be used to get the url of current or previous page.
It is however advised to remember that this referrer is “Browser Referrer” not the “Human Known Referrer”.
The case where a user clicks the browser back button, for example pageA -> pageB -> pageC -> (back button) pageB, current pageB’s referrer is pageA, not pageC.
Console Logs Polyfill
The following is not a special polyfill. It just makes sure that calling console.log
API doesn’t throw error event to client-side.
if (typeof console === "undefined") {
var f = function() {};
console = {
log: f,
debug: f,
error: f,
info: f
};
}
EncodeURI or EncodeURIComponent
Understand the difference between escape()
encodeURI()
encodeURIComponent()
here.
It’s worth mentioning that using encodeURI()
and encodeURIComponent()
has exactly 11 characters different.
These characters are: # $ & + , / : ; = ? @ more discussion.
YOU MIGHT NOT NEED JQUERY
As the title said, you might not need jquery. It’s really useful if you are looking for some utilities code - AJAX EFFECTS, ELEMENTS, EVENTS, UTILS
You Don’t Need jQuery
Free yourself from the chains of jQuery by embracing and understanding the modern Web API and discovering various directed libraries to help you fill in the gaps.
http://blog.garstasio.com/you-dont-need-jquery/
Useful Tips
Load Script with Callback
It’s similar to asynchronous script loading with additional callback event
function loadScript(url, callback) {
var script = document.createElement('script');
script.async = true;
script.src = url;
var entry = document.getElementsByTagName('script')[0];
entry.parentNode.insertBefore(script, entry);
script.onload = script.onreadystatechange = function () {
var rdyState = script.readyState;
if (!rdyState || /complete|loaded/.test(script.readyState)) {
callback();
// detach the event handler to avoid memory leaks in IE (http://mng.bz/W8fx)
script.onload = null;
script.onreadystatechange = null;
}
};
}
Once Function
Implementation of the function once
Quite often, there are functions that are needed only to run once. Oftentimes these functions are in the form of event listeners which may be difficult to manage. Of course if they were easy to manage, it is advised to just remove the listeners. The following is the JavaScript function to make that possible!
// Copy from DWB
// http://davidwalsh.name/javascript-once
function once(fn, context) {
var result;
return function() {
if(fn) {
result = fn.apply(context || this, arguments);
fn = null;
}
return result;
};
}
// Usage
var canOnlyFireOnce = once(function() {
console.log('Fired!');
});
canOnlyFireOnce(); // "Fired!"
canOnlyFireOnce(); // nada. nothing.
Pixel Ratio Density
To better understand terms such as pixel, ratio, density, dimension are while developing mobile web – the following links can provide more insights:
Get Style Value
Get inline-style value
<span id="black" style="color: black"> This is black color span </span>
<script>
document.getElementById('black').style.color; // => black
</script>
Get Real style value
<style>
#black {
color: red !important;
}
</style>
<span id="black" style="color: black"> This is black color span </span>
<script>
document.getElementById('black').style.color; // => black
// real
var black = document.getElementById('black');
window.getComputedStyle(black, null).getPropertyValue('color'); // => rgb(255, 0, 0)
</script>
ref: https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle
Check if Element in Viewport
There is more here.
function isElementInViewport (el) {
//special bonus for those using jQuery
if (typeof jQuery === "function" && el instanceof jQuery) {
el = el[0];
}
var rect = el.getBoundingClientRect();
return (
rect.top >= 0 &&
rect.left >= 0 &&
rect.bottom <= (window.innerHeight || document.documentElement.clientHeight) && /*or $(window).height() */
rect.right <= (window.innerWidth || document.documentElement.clientWidth) /*or $(window).width() */
);
}
Check if Element is Visible
var isVisible = function(b) {
var a = window.getComputedStyle(b);
return 0 === a.getPropertyValue("opacity") || "none" === a.getPropertyValue("display") || "hidden" === a.getPropertyValue("visibility") || 0 === parseInt(b.style.opacity, 10) || "none" === b.style.display || "hidden" === b.style.visibility ? false : true;
}
var element = document.getElementById('box');
isVisible(element); // => false or true
Get Viewport Size
var getViewportSize = function() {
try {
var doc = top.document.documentElement
, g = (e = top.document.body) && top.document.clientWidth && top.document.clientHeight;
} catch (e) {
var doc = document.documentElement
, g = (e = document.body) && document.clientWidth && document.clientHeight;
}
var vp = [];
doc && doc.clientWidth && doc.clientHeight && ("CSS1Compat" === document.compatMode || !g) ? vp = [doc.clientWidth, doc.clientHeight] : g && (vp = [doc.clientWidth, doc.clientHeight]);
return vp;
}
// return as array [viewport_width, viewport_height]
User Tracking
Assuming that an Evil Advertisement Company wants to track a user, Evil may well generate a personalized unique hash by using fingerprinting. However, Ethical Company uses cookies and offers Opt-out solution.
Opt Out
DIGITAL ADVERTISING ALLIANCE, POWERED BY YOURADCHOICES provides a tool that helps anyone to opt-out from all the participating companies.
WTF
Misspelling Of Referrer
Fun fact about why the HTTP Request Header having the field name referer
not referrer
According to the Wikipedia
The
misspelling of referrer
originated in the original proposal by computer scientistPhillip Hallam-Baker
to incorporate the field into the HTTP specification. The misspelling was set in stone by the time of its incorporation into theRequest for Comments
standards documentRFC 1945
; document co-authorRoy Fielding
has remarked that neither “referrer” nor the misspelling “referer” were recognized by the standardUnix spell checker
of the period. “Referer” has since become a widely used spelling in the industry when discussing HTTP referrers; usage of the misspelling is not universal, though, as the correct spelling “referrer” is used in some web specifications such as theDocument Object Model
.
CSS Flexible Box Layout Module
Be sure to double-check the flexbox functionality in a different browser, especially the partial support in IE10/11.
Template
This guide provides templates and boilerplates to building an SDK.
Books/Nice to Reads
(inspired by http-api-design)
Contributors ✨
Thanks goes to these wonderful people (emoji key):
Huei Tan 📖 |
Pascal Maniraho 📖 |
Adam 🖋 |
This project follows the all-contributors specification. Contributions of any kind welcome!