AOL Toolbars / Yedda Integration

Hosting JASPAX - JavaScript Page Extenders

VERSION 0.92
9 DECEMBER, 2009

YANIV GOLAN

AOL Toolbars / Yedda Integration

Version

Primary Author(s)

Description of Version

Date Completed

0.8 0.9 0.91 0.92

Yaniv Golan Yaniv Golan Yaniv Golan Yaniv Golan

Internal Shared with AOL Toolbar team Integrated comments following review with Steve Rice Created following conclusions from 1st prototype created by the Toolbar team Added LoadDelay Added Includes (white list) Added implementation checklist Renamed control file to config.xml Clarified host-id format Added secret key exchange between host and client Added method for the script to notify the host about request to remove the JASPAX code.

Jan 19, 2009 Jan 25, 2009 Feb 4, 2009 May 3, 2009

75292669.doc

Page 2

AOL Toolbars / Yedda Integration

TABLE

OF

CONTENTS

1. ABOUT THIS DOCUMENT................................................................................................................................................5 2. TERMINOLOGY...............................................................................................................................................................6 3. JASPAX HOST - FLOW DIAGRAM.................................................................................................................................7 4. WHY SO MANY TYPES OF SCRIPTS?...................................................................................................................................8 5. CONFIGURING JASPAX................................................................................................................................................9 5.1 OVERVIEW...................................................................................................................................................................9 5.2 FORMAT......................................................................................................................................................................9

5.2.1 Format Notes.............................................................................................................................10

5.3 LOCATIONS................................................................................................................................................................10

5.3.1 Master Config............................................................................................................................10 5.3.2 Domain-Specific Config.............................................................................................................10

6. DISABLING JASPAX REMOTELY.................................................................................................................................11 6.1 OVERVIEW.................................................................................................................................................................11 6.2 SEMANTICS OF MISSING CONFIG FILE..............................................................................................................................11

6.2.1 Master Config............................................................................................................................11 6.2.2 Domain-Specific Config.............................................................................................................11

6.3 LOGIC.......................................................................................................................................................................11 7. LOCATE THE JASPAX DOMAIN SCRIPT.......................................................................................................................13 7.1 7.2 7.3 7.4 OVERVIEW.................................................................................................................................................................13 LOCATION.................................................................................................................................................................13 REDIRECTS................................................................................................................................................................13 SSL CERTIFICATES.....................................................................................................................................................13

8. LOAD & ACTIVATE JASPAX DOMAIN SCRIPT.............................................................................................................14 8.1 LOADING...................................................................................................................................................................14 8.2 ACTIVATING..............................................................................................................................................................14 8.3 JASPAX_DOMAINSCRIPT_INIT........................................................................................................................................14

8.3.1 Inputs.........................................................................................................................................14 8.3.2 Returns.......................................................................................................................................15

9. DISABLING JASPAX THROUGH THE CLIENT UI.............................................................................................................16 10. PAGE SCRIPT MULTIPLEXER.......................................................................................................................................17 10.1 10.2 10.3 10.4 OVERVIEW...............................................................................................................................................................17 OPEN ISSUES............................................................................................................................................................17 DATA MODEL..........................................................................................................................................................17 PAGE SCRIPT FORMAT...............................................................................................................................................18

11. HOST IMPLEMENTATION CHECKLIST............................................................................................................................19

75292669.doc

Page 3

AOL Toolbars / Yedda Integration

75292669.doc

Page 4

AOL Toolbars / Yedda Integration

1. ABOUT THIS DOCUMENT

The following document is part of the technical specification of the AOL Toolbars / Yedda integration. It complements the functional specification of the integration, provided in a separate document. While the specification is focused on the Yedda Toolbar integration, an effort has been made to describe a generic infrastructure (JASPAX), that allows for additional toolbar JavaScript-based integrations to be built using the same infrastructure.

75292669.doc

Page 5

AOL Toolbars / Yedda Integration

2. TERMINOLOGY
JASPAX Host: Browser-resident code (toolbar, plugin) which is responsible for identifying, loading and injecting a specific JavaScript code into the web page currently viewed in the browser. JASPAX Domain Script: A JavaScript file which implements a domain-specific functionality. Page Script Multiplexer: A specific Domain Script which given the current page URL and configuration data identifies, loads and activates a Page Script. Page Script: JavaScript code which is relevant to a specific set of pages in the domain, as indicated by the associated regular expressions.

75292669.doc

Page 6

AOL Toolbars / Yedda Integration

3. JASPAX HOST - FLOW DIAGRAM

JASPAX Host Detects navigation to a new page

Kill switch on ?

Identify JASPAX Domain Script

Toolbar.exe

Do nothing

Load & Activate Domain Script

Domain Script 1

Domain Script 2: Page Script Multiplexer

Domain Script 2

Identify Page Scripts

Load & Activate Page Scripts

Page Script 1

Page Script 2: Popbar Script

Page Script 3

Identify Popbar Page UI

Load & Initialize Popbar Page UI

Display Popbar Page UI

75292669.doc

Page 7

AOL Toolbars / Yedda Integration

4. WHY

SO MANY TYPES OF SCRIPTS?

We would like the host code to be as simple and reliable as possible, and to contain as little applicationspecific logic as possible, to enable a wide range of applications. At the same time, it is desired to allow the host to be able to cache the script files effectively. Hence, the only type of scripts the host needs to deal with is Domain Scripts. Conceptually there is 1 domain script for each domain. However: If multiple domains require the same functionality, a single domain script file can be served to the host for multiple different domain script requests. If a domain requires substantially different functionality for different parts of the site, the domain script can implement logic to identify the type of functionality based on some criteria, such as the current page URL, and load additional more specialized scripts. All domains requesting a domain-specific domain script will actually be served the same script (i.e. the Page Script Multiplexer). This single shared domain script implements logic which, based on the current page URL and a RegExp-driven configuration data, identifies and loads additional scripts (i.e. Page Scripts) which provide functionality which is relevant for specific groups of pages in the domain.

Both techniques are used in the scheme described below:

Conceivably we could have hard-coded the RegExp-driven logic into the host. The cons of this approach would be: Host implementation more complex and less reliable Hard-coded RegExp logic would require host update to use different logic if needed (say, geodriven logic, promotions and sponsorships, etc)

75292669.doc

Page 8

AOL Toolbars / Yedda Integration

5. CONFIGURING JASPAX
5.1 Overview
It is important that a host will be able to configure the JASPAX-related aspects of the client remotely. It is also important to allow a specific web site to control a subset of the JASPAX-related functionalities of the client. These remote configuration capabilities are enabled using the JASPAX configuration file. This file is stored in a central location accessible to all hosts (a.k.a Master Config). In addition, each web site can publish a website-specific configuration file that configures the relevant subset (a.k.a Domain-Specific Config).

5.2

Format

The JASPAX configuration file is stored in the following XML format:

<Configuration> <Parameters> <LoadDelay>time-to-wait-before-loading-script-secs</LoadDelay> </Parameters> <Includes> <IncludeUrls> <IncludeUrl> url-reg-exp</IncludeUrl>* </IncludeUrls> <IncludeUserAgents> <IncludeUserAgent>user-agent-reg-exp</IncludeUserAgent>* </IncludeUserAgents> <IncludeHosts> <IncludeHost>host-id-reg-exp</IncludeHost>* </IncludeHosts> <Excludes> <ExcludeUrls> <ExcludeUrl>url-reg-exp</ ExcludeUrl>* </ExcludeUrls> <ExcludeUserAgents> <ExcludeUserAgent>user-agent-reg-exp</ExcludeUserAgent>* </ExcludeUserAgents> <ExcludeHosts> <ExcludeHost>host-id-reg-exp</ExcludeHost>* </ExcludeHosts> </Excludes> </Configuration>

75292669.doc

Page 9

AOL Toolbars / Yedda Integration

5.2.1 Format Notes

* Indicates that the element can appear zero or more times Domain-Specific config cannot use the Parameters\LoadDelay element Domain-Specific config can reference only URLs which are below the config URL in the URL hierarchy; meaning, a domain-specific config located at http://subdomain.samplesite.com can reference only URLs that conform to the pattern http://subdomain.samplesite.com/*. If it does reference URLs outside this hierarchy, these entries will be ignored.

5.3

Locations
5.3.1 Master Config

The Master Config must be stored at http:/jaspax.aol.com/v1/config.xml.

5.3.2 Domain-Specific Config

Domain-Specific Config must be stored at http://domain/jspxcnfg.xml, where domain is the domain for which the configuration data is specified. Example: http://www.example.com/jspxcnfg.xml

75292669.doc

Page 10

AOL Toolbars / Yedda Integration

6. DISABLING JASPAX REMOTELY

6.1 Overview
It is important that a host will be able to disable JASPAX functionality remotely. JASPAX functionality can be disabled either centrally by the creators of the host, or for specific web sites by the operators of a specific domain. Before proceeding to identify and load plugins, all JASPAX hosts must check 2 locations: 1. Master Config 2. Domain-Specific Config It is possible to disable JASPAX at the following levels: All sites (Master Config only) Subset of sites (Master Config only) Subset of a site (Master or Domain-Specific Config) Subset of user agents (Master or Domain-Specific Config) Subset of hosts (e.g. toolbar) (Master or Domain-Specific Config) If excluded, the injection code should do nothing.

6.2

Semantics of missing config file

6.2.1 Master Config

If the Master Config file does not exist at the location specific in Section 5.3.1, it should be assumed that the JASPAX functionality should be disabled for all sites and user agents.

6.2.2 Domain-Specific Config

If the resource does not exist at the locations specified in Section 5.3.2, it should be assumed that the JASPAX functionality should be enabled or disabled according to the Master Config data only.

6.3

Logic

1. If cached Master Config data does not exist or expired, try to retrieve it. Otherwise use the cached data; 2. If failed to retrieve, cache this fact and disable! 3. Compare current host id with the excluded host ids in the Master Config data; if matches, disable! 4. Compare current user agent with excluded user agents in the Master Config data; if matches, disable!

75292669.doc

Page 11

AOL Toolbars / Yedda Integration

5. Compare current url with excluded urls list in the Master Config data; if matches, disable! 6. If cached Domain-Specific Config data for current domain does not exist or expired, try to retrieve it. Otherwise use the cached data; 7. If failed to retrieve, cache this fact. 8. Compare current host id with the excluded host ids in the Domain-Specific Config data; if matches, disable! 9. Compare current user agent with the excluded user agents in the Domain-Specific Config data; if matches, disable! 10. Compare current url with the excluded urls list in the Domain-Specific Config data; if matches, disable! Note that the easiest and fastest way to disable JASPAX functionality at once for all sites (hence completely disabling the plugins functionality for all running toolbars) is to simply delete the Master Config file. The actual functional disable will happen only once all cached copies of the config files expire. Hence, the files should be marked as non-cachable, and the host should cache the data for a relatively short time.

75292669.doc

Page 12

AOL Toolbars / Yedda Integration

7. LOCATE
7.1

THE

JASPAX DOMAIN SCRIPT

Overview

A JASPAX Domain Script is a per-site JavaScript file which is injected into the current page by a host. Only one JASPAX Domain Script is supported per site & host. The Domain Script JavaScript may be cached by the host for the time period indicated by the relevant HTTP headers. However, if cached, the activation logic must still be followed per each page.

7.2

Location

The host should retrieve the Domain Script from the following URL:
https://jaspax.aol.com/v1/domainscripts/get?<domain-name>.js

Where domain-name is the domain part of the URL for which the Domain Script is being loaded. For example, if viewing https://business.blogs.cnn.com/2008/12/11/what-if-interest-rate-cuts-arent-enough/ The domain name is business.blogs.cnn.com And the Domain Script JavaScript file URL is
https://jaspax.aol.com/v1/domainscripts/get?business.blogs.cnn.com.js

7.3

Redirects

Hosts must respect and follow and HTTP 30x redirects it may receive as a response to a request to a domain script.

7.4

SSL Certificates

Hosts must validate the SSL certificate returned by jaspax.aol.com to prevent man-in-the-middile attacks.

75292669.doc

Page 13

AOL Toolbars / Yedda Integration

8. LOAD & ACTIVATE JASPAX DOMAIN SCRIPT

8.1 Loading
Once identified, the domain script is loaded, injected into the current page and executed in the context of the current page.

8.2

Activating
hostId, domain, userAgent,

Every JASPAX Domain Script must implement, at the minimum, the following function: function jaspax_domainScript_init(secret, secsSincePageLoad)

This function must be invoked by the host exactly once for each page. The host should call this function at a point in the page lifetime which is equivalent to DOMContentLoaded. The host must not call this function earlier in the page lifetime than the equivalent of DOMContentLoaded. Implementation note: a cross-browser implementation of the Mozilla-specific DOMContentLoaded can be found here.

8.3
secret

jaspax_domainScript_init
8.3.1 Inputs
String; a secret value exchanged between the host and the loaded script; both host and script should keep this value in memory. The script will use this value in any callback function provided by the host, and the host should reject any callback that does not include the correct key. This will help preventing unauthorized JavaScript code in the page from invoking host callback functions.

hostId

String; a unique id for the host (e.g. aol;mapquestion;1.0) This value should uniquely identify a specific host. It must be specific enough to allow for host-specific configuration, and it must be readable to 3rd parties as well. The exact format of this string is up to the host developers; it is their responsibility to ensure its uniqueness and readability. All hosts IDs issued by AOL developers must conform to the following format: aol;host-name;host-version e.g. aol;mapquest_toolbar;1.0

domain

The domain name of the page for which the script is being loaded. This is identical to the value passed in section 7.2 Location

75292669.doc

Page 14

AOL Toolbars / Yedda Integration

userAgent secsSincePageLoad

The browsers user agent string value The elapsed time (in seconds) since the page started loading (e.g. the user navigated to the page URL). If unknown to the host, value should be -1. This value will be used by some implementations to calculate a delay before showing a specific user interface.

8.3.2 Returns
True if successful. If false, this plugin should be disabled for the entire browser session as if it appeared on the exclude list.

75292669.doc

Page 15

AOL Toolbars / Yedda Integration

9. DISABLING JASPAX

THROUGH THE CLIENT

UI

The client UI displayed by the injected code should provide a user interface that will let the user turn off the JASPAX-provided experience completely in a specific machine (for the logged in user). To enable this, the host should expose a window.external function with the following signature: jaspax_host_disableAll(secret) The function receives a single parameter secret, which should be the same value passed earlier by the host to the jaspax_domainScript_init function. If the values dont match, the host should ignore the call. If the value do match, the host should store in the context of the logged in user on the machine an indication that the JASPAX code should not be loaded in the future. The client is responsible for removing the user experience for the current page after calling the host.

75292669.doc

Page 16

AOL Toolbars / Yedda Integration

10. PAGE SCRIPT MULTIPLEXER

10.1 Overview
The Page Script Multiplexer (PSM) is a specific JASPAX Domain Script, and is the one well be focusing on. As noted above, its code is injected into the current page, and its jaspax_domainScript_init is called when appropriate. The goal of the PSM is to identify, load and activate the list of relevant Page Scripts for the page being viewed right now.

10.2 Open Issues

The design of the PSM is not finalized yet. Open issues: How important is Greasemonkey compatibility (if at all) Script initialization through a callback function (as specified now), or through the script global javascript code (like in GM) GM-like @requires and @resource statements

10.3 Data Model

The PSM is driven by the following data structure:
PageSets PageSet* FriendlyName Triggers Exclude* url-reg-exp Include* url-reg-exp ScriptURL ScriptInitJSCallback Parameters Parameter* Name Value

Example:
<PageSets> <PageSet>

75292669.doc

Page 17

AOL Toolbars / Yedda Integration

<FriendlyName>CNN World News Popbar UI</FriendlyName> <Triggers> <Include>http://.*news/.cnn/.com.*</Include> <Include>http://.*hot/.cnn/.com.*</Include > </Triggers> <ScriptURL>http://jaspax.yedda.com/scripts/ps/cnn/news-hot-1.js</ScriptURL> <ScriptInitJSCallback>yedda_cnn_worldnews_init</ScriptInitJSCallback> <Parameters> <name1>value1</name1> <name2>value2</name2> <name3>value3</name2> </Parameters> </PageSet> </PageSets>

Note that the JASPAX Domain Script implementing the PSM can be automatically generated from this data. ScriptURL is used to load the Page Script. The returned script is compatible with JSON-based insertions into the page. If multiple page scripts match the current URL, all matching page scripts should be loaded and activated. ScriptInitJSCallback is the name of a JavaScript function implemented by the script specified by ScriptURL which is used to initialize the script.

10.4 Page Script Format

The Page Script JavaScript file must, at the minimum, implement the function specified by the ScriptInitJSCallback parameter. The function signature must be as follows: function params) scriptInitJSCallback-function-name(hostId, userAgent, url,

The init function will be called exactly once for each Page Script per page. It will be called by the domain script jaspax_domainScript_init function. Note that while it is guaranteed that the DOM is available at this point (e.g. DOMContentLoaded), it is not guaranteed that all resources were loaded (e.g. not body.onload). hostId: string, unique id for the host (e.g aol;toolbar;mapquest;1.0) userAgent: The user agent url: The URL of the current page params: Array with the specified parameters and their values. returns: true if successful. If false, this plugin should be disabled for the entire browser session as if it appeared on the exclude list.

75292669.doc

Page 18

AOL Toolbars / Yedda Integration

11. HOST IMPLEMENTATION CHECKLIST

Following is a list of common pitfalls when implementing a JASPAX host (e.g. Toolbar with JASPAX support). It is strongly suggested that you review this list before completing the implementation. 1. Verify that SSL certificate on jaspax.aol.com is valid, at least once per browser session. In Internet Explorer, issue a request using WinINET, use the INTERNET_FLAG_SECURE flag and do not add any ignore flags. Make sure that the function call returns without an error. For more details, see http://support.microsoft.com/kb/168151. (more info at Section 7.4) 2. If jaspax_domainScript_init returns false, do not try to load this domain again in this browser session (more info at Section 8.3.2) 3. If the master config file is missing (e.g. 40x), do not run any of the JASPAX code (no checking for domain-specific config, no injection of anything into the DOM, nothing) (more info at Section 6.2.1) 4. If the request for the domain script returns a redirect (30x), follow the redirect (more info at Section 7.3)

75292669.doc

Page 19