The subown.js JavaScript library is the core element of Subown. It communicates with the Subown server, traverses the DOM and renders Subown share elements (Subown Share Button, Subown Share Link). Additionally, it initializes the rendering of AdSense ad units by downloading the adsbygoogle.js script from //pagead2.googlesyndication.com/pagead/js/adsbygoogle.js.
This document explains how to add the subown.js JavaScript library to your site.
Before you begin
If you haven't already signed up, create a Subown Client Id.
A simple JavaScript snippet For Adding subown.js To Your Site
Select, copy and paste the following JavaScript code snippet (the "Snippet") into all your pages that integrate Subown:
- Add the code right before the closing
</body>tag of your page's HTML source code
The Snippet does 5 main things:
1. Creates a <script> element that starts asynchronously downloading the subown.js JavaScript library from //subown.com/js/subown.js.
The advantage of the asynchronous code is that it's guaranteed never to get in the way of other parts of your web page loading. Your users will be able to load the High-Quality content of your pages, even if they're having trouble loading the subown.js JavaScript library.
2. Initializes a global so function that allows you to schedule commands to be run once the subown.js JavaScript library is loaded and ready to go.
3. Adds a command to the so() command queue to create a new user object that is used to authenticate the page with Subown's services for the property specified via the YOU_SUBOWN_CLIENT_ID parameter.
4. Checks on page load if the so() command queue confirms the successful download of subown.js. On failure it creates a <script> element that starts asynchronously downloading the adsbygoogle.js library from //pagead2.googlesyndication.com/pagead/js/adsbygoogled.js. (The adsbygoogle.js script is required to fill unfilled ad slots.)
5. Specifies a fallback for the subown.js JavaScript library with a timeout of 30 seconds, that way in case Subown network problems occur, the adsbygoogle.js will be automatically loaded.
Custom implementation requires modifying the last line of the Snippet (the sid command, so("sid",YOUR_SUBOWN_CLIENT_ID);). Please do not change any other part of the code that loads the subown.js JavaScript library or initializes the so() command queue function.
Next step
By implementing the Snippet that loads the subown.js JavaScript Library into your website you've successfully completed part 2 of The Ultimate 5-Point Guide To Upgrade Your Website With Subown.
Now you can add the Subown Share Button to your website.
Advertisement
Documentation - How your website makes an API request using the Subown JavaScript library
Once downloaded by the Snippet, the subown.js JavaScript library does the following:
1. Traverses the DOM and renders <A> elements with class="subown-share-btn" as Subown Share Buttons and throws and error if the DOM doesn't include any such element:
Link tag element with class=subown-share-btn is missing in the DOM. Check out implementation at https://subown.com/get-started/add-subown-share-button-to-your-website.
The Subown Share Button is formatted according to the information in the Subown style sheet, - downloaded from https://subown.com/css/subown.css - which is added as <LINK> tag in the <HEAD> of the document.
2. Determines the single, preferred URL that is shared through Subown (the "URL to Share")
3. Performs URL percent-encoding on the URL to Share and completes the href attribute of each <A> element with class="subown-share-btn" and class="subown-link" by adding a field to the base URL (https://subown.com/become-partial-owner-of-high-quality-pages) with field name url and field value equal to the properly escaped URL to Share. Example:
https://subown.com/become-partial-owner-of-high-quality-pages?url=https://www.example.com4. Reads the Subown client ID, - specified via the YOUR_SUBOWN_CLIENT_ID parameter in the last line of the Snippet - and throws an error if it's invalid:
Invalid Subown client ID. Check out implementation at https://subown.com/get-started/load-subown-javascript-library
5. Scans the DOM for <INS> elements with class="adsbygoogle" (known as the "AdSense ad code") and throws the following error if no AdSense ad code can be found in the DOM:
<INS> tag element with class=adsbygoogle is missing in the DOM. Check out implementation at https://subown.com/get-started/implement-subown-ads-for-adsense
6. Throws the following error if not every AdSense ad code includes the adsbygoogle.push() command:
adsbygoogle.push() is missing on at least one ad unit. Check out implementation at https://subown.com/get-started/implement-subown-ads-for-adsense
7. Extracts the Page ID from the page's URL.
8. Sends a POST request to the Subown Server (https://subown.com/subown). Subown receives information including the Page ID (if any), the URL to Share, encrypted information about previous API requests (the Key, see below), information about the page's host and path structure, the page's referrer (if any), and information about the browser's cookies functionality. Subown returns a JSON object with information including the page's current number of users connected with the page as Partial Owners (the "Count"), the legitimate publisher ID and slot ID (if any, derived by the Subown Algorithm), and a key that includes encrypted information about the JSON object returned by Subown (the "Key"). If the Count is greater than 5 it gets displayed within a bubble next to the rendered Subown Share Button. The Key is stored into the session storage of the browser and included in subsequent POST request initiated by the subown.js JavaScript library. The Key is used for verification purpose and to maintain state information as a user navigates different pages on your site. A valid Key allows Subown to evaluate if a user has returned to the specific site and it can retrieve previously saved information of the request - leading to more efficient and increased execution time.
9. Replaces - only if the legitimate publisher ID and slot ID belong to a Partial Owner or to Subown - the AdSense ad units' ad client parameter with the value returned by the Subown server, and the ad units' ad slot parameters with the values called by subown.push({ params: { ad_type: AD_TYPE }}).
10. Finally, downloads the adsbygoogle.js Javascript library from //pagead2.googlesyndication.com/pagead/js/adsbygoogle.js once the above steps have been executed by the subown.js script, and adds another command to the so() command queue to prevent the Snippet to call the fallback function to load adsbygoogle.js on failover.
Troubleshooting
Something went wrong? We recommend that you thoroughly test all your pages that load the subown.js JavaScript library. Check your browser's JavaScript error console, where subown will display messages about any noticed configuration problem - including a link to troubleshoot common setup mistakes.
The JavaScript error console can be opened by using the keyboard shortcut Control + Shift + J.
Attribution
Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 3.0 Attribution License.
Advertisement
