Introduction
The Izyware Chrome extension lets you authenticate, send and retrieve information, and run Izyware Automation Tasks right from your browser.
Common Usage Scenarios
You may package and deploy your Izyware automation app in the following use cases:
- Rapid software prototyping and exploration: This can happen locally an on a single client without having to go thourgh the full deployment pipeline. This should improve your teams iteration velocity. For example:
* Provide an additional user interface above the the existing website or SAS dashboard
* Augment and change the behavior of features for any website
- Data scraping
- Cross website functionality integration and automation
- Collecting usage metrics and data analytics
Please refer to the Izyware knowledge base center for detils and white papers.
Installaion
Enterprise Device Management
Use the Device Extension application from your account to register and activate the extension.
After your device has been registered, you should be able to see the following screen:
This will create a record in the tagidtoken
store and will associate the current tagidtoken.userid
to session.ownerId
to the idtoken assigned to the extension.
Associations
It is important to remember that the extensions can be associated with "buckets" manually regardless of how or by whom the extension was activated: If an extension was activated while logged in as a particular account that should not be material to the core workflow because the the bucket association will detemine the currenct contextual focus of the end user and how the device may be accessed from the information bucket hierarchy. It is for this reason that the framework provides that tag_idtoken.bucketid field. The organization may review the list of devices associated with members of a group through the Data Collection > Device Manager application and set the bucketId for the device may be set from this area.
Scripting Environment
Starting with V5 and forward, izy-proxy chains are supported. You may use the familiar command pattern:
doChain([
['chain.importProcessor', 'izyware/extensions:chainprocessor', {
verbose: true
}],
['deviceextension.querystate'],
...
['deviceextension.run', {
qs: ...
}]
])
Extension Features and Configuration Options
- UI Button: This may be used to launch apps and services on demand. The default behavior is "broadcast to all tabs" which will perform the following for all the tabs:
window.postMessage("izywaretoolbarbuttonclicked", *)
- Cloud Auto Sync: Activated by setting chromeextensionmodetoolbar_autocloudsync to enabled. Note that the general.active flag wont affect the cloud sync. Allows executeScript and query style commands from the ping URL. See ping URL for more details.
- Interval: You can override cloudSyncAudoCheckIntervalIsMs via the global key/value store. Min and Max values are not changeable.
- Ping Url: You can override cloudSyncUrl via the global key/value store.
- App Delivery: To disable this feature, just flip the general.active flag. Note that the general.active flag wont affect the cloud sync.
- Tab Delivery Method: This method is susceptible to CSP limitations. For better performance switch this to Inject Tab Script From Background. To modify this behavior, you should update
izyware/extensions/apploader.js
and rebuild the extension. This is currently set to
Create Script Element at head[0]
- Initial Bootstrap (Direct Tab Network): Determines how the IzyCloud is contacted for the intial bootstrap payload for content script. When extension caching is enabled, this call will only happen once. Re-releasing the content script package will flush this cahche and force it to reload. To change this behavior you must update
izyware/loader/extension/contentscript.js
and rebuild the extension.
- Package Payload (Transport Overlay via Background): Determines how the IzyCloud is contacted for inquiring about the status of the content script payload. Notice that even when the contentscript app is cached locally, the IzyCloud is still contacted for it is possible that a trigger payload may be defined for the extension USERIDTOKEN. However, the current tabs network traffic is never affected when this option is set. You can customize this behavior but modifying the payload returned by bootstrap1.php endpoint.
- Cache Management
Configuration Options
The following configuration options are common:
Visible button, with extention as a simple tab launcher for a landing page: In this scenario the registerLink* is set to the desired landing page and the extension is never activated. Each time the user clicks the button a new tab will be opened with the URL.
Visible button used to notify current tab: In this scenarios the button click will use the notification framework to 'notifyCurrentTab'. If the current tab happens to have a script subscribed to notifications, it will pick up the notification (i.e. IzyCloud window manager izytoolbar/contentscript*). It is important to note that the window manager in this scenario will run in the context of the tab and is subject to the security restrictions imposed by the tabs domain.
- Visible button used to notify the system:
TaskRunner Mode
In order to use the extension from automation framework, you can use the automation project to create an project card with the following properties:
- runtimeid: deviceid
- execusion model: RP
- scheduling: reruns are not currently support
- execution tracking:
* outcome should reference the raw_tokendata.id row
The task implementation will record the results in the data collection app. The following parameters are supported:
- statecapture5.5
- statecapture
- default (httptrace)
- testLargePayload5.5
- clearall
Legacy
The item is added to
token_triggers
datastore. The following chain of events is required:
- When
Create Script Element at head[0]
option is turned on and user opens a new tab or refreshes an existing one, izywaretoolbar/contentscript will be loaded into the tab which will in turn query the package loader. This is predicating on user taking action which makes automation more difficult. In addition, this approach has limitations regarding CSP policies depending on the tab content.
- package loader scans tokentriggers datastore and will include the trigger package depending on the typ of tokentrigger (once, always, etc.) and will update the state to 2.
izywaretoolbar/contentscript,,timestamp,trigger,/ Cached: increased max size to 1.9MB /...
Publishing Extension Enabled Apps
Izyware Micro Apps Button
You can use the pre-built and deployment ready extension in the
chrome store to create, use and distribute extension enabled apps.
The simplest way is to clone that app. These apps use the embedded form of the izywaretoolbar/debug
app:
var modtask = function(push) {
var pkgid = 'izywaretoolbar/debug';
push({
parts: 'text',
what: 'Loading ...'
});
modtask.modcontroller.doChain(modtask, [
['frame_importpkgs', [pkgid]],
function(_push) {
push({
parts: 'ext',
what: pkgid + '/viewer/top'
})
}
]);
}
Internally, this app will:
- verify that the extension has been installed. If not it will walk the user through the wizard (enabled by the
storeinstaller
app) and install the chrome store extension. If it is installed, it will just show the configuration and info panel for the extension.
use the izywaretoolbar* for routerid to communicate to the IMAB extension
set the izywaretoolbar
as the namespace for the package and scripts. The izywaretoolbar/contentscript* develops a simple packagemanager that allows multi app installations.
by default, this will have caching and transport override* features enabled. Caching may be turned on/off via the settings interface. Transport override is embedded into the bootstrap layer loaded through runInBootstrapContext inside https://izyware.com/bootstrap1.php. See izycloud deployment engine for more details.
Building The Extension From Scracth
Latest Version
./ldo.sh mship izywaretoolbar/5/extension/chrome/build
cd izywaretoolbar/5/extension/chrome;npm run test
Developing and testing new device commands using the developer mode
Follow these steps:
- Bump the extensionVersion in build.js
- Rebuild the extension and load into browser (note the path change)
- Edit
autocloudsync/api/ping?generateDeviceCommand
* Add the new parameters value for the task object (i.e. statecapture5.x)
* Leave encryptCommand = true on. This will only affect the command sent.
* Specify
* action
* queryObject
* skipOutcomeDataDecryption: settings this to true will skip decrypting the outcome.data field before storage into raw_tokendata. This will depend on the specific implementation details of the action.
- Edit
chrome/codegen/chrome/template/chrome/background.js
* Set the
forceCloudSyncOnStartup
to true
* Update the modtask.config.verbose
keys
* processCommand
* handleCloudSyncResponse
* Extend the modtask.actions section
Generic Instructions
You can clone the
izywaretoolbar package that is the basis for the IMAB. While this process is more complicated, it will provide the greatest flexibility. You should follow these steps:
- create a build.js using the sample provided in the izywaretoolbar package and then do:
./ldo.sh mship izywaretoolbar/build
- decide on a unique routerid that can be used to activate and communicate with the extension:
- The activation can be done via the
storeinstaller app.
- Client packages will use the izyware/extensions package api library to communicate
- create/clone the popup and contentscript codes
IzyCloud Packages Involved (for cloning purposes)
- Popup to content script notifier: {appid}/popupnotifier
- Content Script: {appid}/contentscript
Samples
- To test the plumbing for your content script, clone the following into your contentscript
package name: izywaretoolbar/samples/contentscript
module name: viewer/top
Builder Tool
The reference sample can be found in the
izywaretoolbar package. This will simply use the following:
var cfg = { ... }
var path = modtask.ldmod('izywaretoolbar/codegen/chrome/gen').generate(cfg);
The following are the config options:
appid
This will be utilized in:
- generating the payload directory (cfg.appid + '/chrome/' + cfg.version)
- routerid for api and messaging communication (See below)
icon
If this is specified, it will be put into the luanch bar. If not specified, a transparent image will be used (the clicking on the transparent would still launch the popup. To disable this see the
popup section below).
popup
If this is NOT specified, the
manifest_nopopup.json will be chosen. In this case, the content script is the only item that is present in ecosystem. If this is specified, popup feature is enabled. The popup behavior changes when the plug-in state goes from inactive to active.
Inactive State
The
register section of the popup config will be used. The legacy behavior will show a simple message (defined by headerMsg), asking the user to click on the link. If
openOnClick is set, it will automatically open a tab to the link addr (the user wont even notice the popup window).
Active State
The app section of the popup block will run. The low performance behavior (legacy and fallback) to open an iframe with src set to the link. The advanced version uses caching to get bits locally and will create an iframe with src='data:text/html;... The only limitaion of this approach is that certain features (cookies,local storage, ...) aren't going to be available to the app.
Sample popup config
popup : {
// Either direct link to izyware app launcher site -- or -- embed in your landing page
register : {
headerMsg : 'Izyware Toolbar',
link: 'https://izyware.com/app.html?appid=' + appid + '/register/embedded',
openOnClick : true
},
// 'https://izyware.com/app.html?appid=' + appid + '/popupnotifier'
app : {
pkgName : appid + '/popup',
link: 'https://izyware.com/app.html?appid=' + appid + '/popup',
width : '200',
height : '400'
}
}
Architecture
Active vs. Inactive states
The extension is active when chrome_extensionmode_toolbar_appid is set to a valid value which will specify what packages are run. The content script and popup scripts will only be launched after the extension has been activated. When in the inactive mode, no external package loading/caching will happen.
Chrome Pieces
- Register:: The link that the user has to go to activate the toolbar post download. For wide distros, this will require login.
- Popup:The app that gets iframed in the popup portion.
- Content Script:The app that gets injected in each page.
Loose Coupling via Messaging
The security model will not allow evals or cross frame code exchange but window.postMessage is allowed to exchange data. One challenge with this is synchronizing the communication through postMessage could be challenging due to the asynchronous nature. The solution provided by the framework uses routers and processors.
Routers
routers are pieces that route the requests to the processors. They assign unique IDs to each query and reroutes them back. They also handle errors and timeout conditions. They simply act as a buffer between background script and the web pages:
// 1. reroute to background processor
chrome.runtime.sendMessage(event.data, function (response) {
...
});
// 2. Poll or timeout until hear back ....
setTimeout(function () {
chrome.runtime.sendMessage({ query : { q : 'poll', id : id } },
function (response) {
// Post the response back to requestor
if (response.length > 0) {
var postData = {
type: "TO_PAGE",
query: response
};
window.postMessage(postData, "*");
....
Processors
proccessors service and handle the requests. For example when inside the chrome system, one processor is placed in the background page.
chrome.runtime.onMessage.addListener(
function(request, sender, sendResponse) {
....
Also two routers are setup; one in the content script section and another one in the popup section.
Communicating to Processors from the client scripts
The api clients will need to provide the following:
Specifying the window* object that the router is placed on.
- RouterID that the extension has been built with (e.g. defaultAppstoreInstallerRouterId for the IMAB)
The following are two examples that demonstrate use of this concept in different contexts
Setting up the API inside a webpage
The communication will work as follows:
webpage.window.postMessage
||
contentscript.window.addEventListener('message')
||
contentscript.processor
||
either chrome.runtime.sendMessage or when rootnamespaceaccess == 'contentscript' contentScriptQuery
Even though the page does not have access to the content script context, it shares the window object which the content script has a router 'listening' on, so it may access the apis by:
modtask.api = modtask.ldmod('izyware/extensions/api').
sp('router', window).
sp('routerid', modtask.ldmod('izyware/extensions/addr').getRouterId());
This is the reason why the content script is required for the web pages to be able to communicate. Also, any webpage that was loaded before the installation would need to get refreshed to have a content script attached to it.
Extension Popup (When the button is placed)
This gets iframed through the popup.html. Since popup.html shares the window object with the popup.js which has a router on, the popup app hosted inside the iframe may access the apis by:
modtask.api = modtask.ldmod('izyware/extensions/api').
sp('router', window.parent).
sp('routerid', routeridfortheextension);
Notifications
The the notifiee, will register via:
modtask.ldmod('izyware/extensions/notification').registerCallback(function() {
console.log('This is my callback');
});
The notifier, will use:
modtask.getExtensionApi(function(api) {
modtask.ldmod('izyware/extensions/notification').sp('api', api).notifyCurrentTab();
});
Persistence
izyware/extensions/persistence is the standard persistence library that is used to assign appids, idtokens, etc. to the running extension.
APPID
Older extension content script loaders used \izyware/extensions/chrome/interop\
. The later versions use \izyware/extensions/apploader\
(the interop library had a hack that would allow communication using inline script tags). The main reason for this shift was to move away from tag based communication (i.e. script tab id'ing) to using the unified APIs and the persistence libs.
So instead of calling the interop sync methods, a typical register app would use something like:
modtask.extensionapi = get from shell
modtask.persistence = modtask.ldmod('izyware/extensions/persistence').sp(
'api', modtask.extensionapi);
modtask.persistence.setApp(...
IDTokens
The apploader will auto generate this if not already exists, and stores it.
Global Store
The background page offers a global key value store. It is best to make these available as frame actions:
['frame_getglobal', 'key', modtask]
['frame_setglobal', 'key', modtask]
Note: Chrome Extension Installation
Inline installation has now been disabled. See the release notes from "Chrome Web Store Developer Support" dated Wed, 13 Jun 2018.
Prior to Wed, 13 Jun 2018
For users who browse the Chrome Web Store and find your item, its a very easy one-click process to install it. However, if a user is already on your site, it can be cumbersome for them to complete the installation - they would need to navigate away from your site to the store, complete the install process, and then return.
As of Google Chrome 15, you can initiate app and extensions installations "inline" from your site. These apps and extensions are still hosted in the Chrome Web Store, but users no longer have to leave your site to install them. See this [link]chromeinlinelink
Service Dependencies
izywaretoolbar/5/dashboard:info/api
izywaretoolbar/5/autocloudsync
Known Issues
* statecapture5.5 does not currently support tab and device metadata and thus is incomplete with the newer version. it must support
* tabs
* device metadata, geometry, etc.
* networking info
* the httptrace is missing the success boolean value and reports the task as failed.
* state processors prior to 5.5 release have issues where
* state might be too large: the workaround is to add filters to the query such as mydomain.com
* concurrency all tabs will hit the cloud concurrently and can potentially impact the task state.
- the OOBE default setting for contentscript should be disable
- scripting
* httprequest signature is incompabitble with izy-proxy: change "data" to body".
* fix timeout issue where timeout in the query is not honored.
* remove the following redundant features
* payloads has been migrated to IB > Bucket > Device S
* triggers > Automation
* upon click redirect to the information bucket item
* new features
* consolidate button: when we reregister a device, just set all the old tokens to the new ones
* archive and delete inactive device
ChangeLog
V7.4
- 74000003: implement getAllowedCollaboratorsForSession and limit to members of peer groups security feature
V7.1
- 71000001: add taskId metadata to cloud sync button in the dashboard
* allows automation to trigger a new task on button click.
* helps in desktop automation workflows
V6.9
- 69000013: add ability to manually trigger cloud sync from the dashboard
* useful for debugging and troubleshooting purposes
- 69000012: implement parameters=clearall, rename to skipEncryption to skipOutcomeDataDecryption
- 69000011: implement parameters=testLargePayload5.5 device action
* useful for stress testing the platform
- 69000010: dashboard - capture cloudSyncUrl and cloudResponseUrl
- 69000009: autocloudsync/api/cb - capture errors for raw_tokendata storage in the taskoutcome. implement skipEncryption metadata in the chainOutcome protocol
* prior to this, the error would have been logged (if turn on) to background.js [background.handleCloudSyncResponse] result and invisible to the shadow maintainace account,
* skipEncryption will allow implementation of new device commands in addition to statecapture, etc.
- 69000008: use whereClauseForAllVisibleCollaboratorsBasedOnGroups
- 69000001: implement browserextension query card for the autoproj
* useful in debugging and implementing extensioned based apps
* updated
V5.6
- 56000003: dashboard app - update to use version prefixed api package. Show extension version in app.
- 56000002: publish izywaretoolbar/5/izyware/extensions package
- 56000001: bug fix for modules/getmachinestate-setproxy. add documentation for publishing apploaders
V5.5
- 55000030: update appstore image collateral
- 55000029: provide 512-bit encryption for user data stored in the extension
- 55000028: provide the deviceExtensionVersion key
{
rootnamespaceaccess: 'modtask',
f: 'getVal',
p: 'deviceExtensionVersion'
}
- 55000027: extension - replace commandId with relayState object
* This will provide more extensibility for future tasks
- 55000026: extension - implement callback processor. add forceCloudSyncOnStartup and end to end tests.
* forceCloudSyncOnStartup will improve the developer experience
* extend the task parameters to statecapture5.5
- 55000025: extension - add tokenizer and response processor
- 55000024: chainProcessor - add lzu data compression
- 55000023: extension/api - support single query format
['.run', {
q: {
n: 'gpu',
f: 'calc.faceMesh',
p: {}
}
}]
- 55000022: logging - add configuration flags for each logging sub system
- 55000021: test - improve mock user agent module and add sample data for chrome object model
- 55000020: add runTestChainItemsAtStartup flag
* useful for smoketesting the extension builds
- 55000019: implement chainProcessorModule for extension background
* provides consistency with izy-proxy framework
- 55000018: extension/api - add verbose flag
- 55000017: extension - fix setTimeout memory leak
* improves performance for production and test environments
- 55000016: extension builder - add terminateExtension features for testing.
- 55000015: extension fix direct unversioned references to routing component to relative strings.
- 55000014: extension builder - virtualize module paths by using extensionInlinePath
- 55000013: bootstrap capture non success outcomes. add state capture successful outcome message
- 55000012: izywaretoolbar/5/autocloudsync utilize alsoCaptureInProgress. capture non success outcomes accurately.
- 55000011: autocloudsync add waiting for runner state
- 55000010: izywaretoolbar/5/bootstrap provide more granular reporting using task progress apis
- 55000009: support end-point for progressTask.
- 55000008: use the task parameters input for customizing actions. add completion functionality and unit tests.
* default is httptrace
* add support for statecapture
- 55000008: add option to log referer for localLogging
- 55000007: add showDebugInfoInClientBrowser flag to the http tracer and set default to false.
- 55000006: cloudsync - add better logging and http tracing and exlucde izyware url targeting.
* use modtask.localLogging to enable/disable server side logging grouped by idtokens
* use modtask.useHttpTrace to bypass task runner and only trace tabs would be calls to apploader.
- 55000005: remove unwatned console.logs
- 55000004: tie autocloudsync to taskrunner
- 55000003: implement izywaretoolbar/5/bootstrap
* generates the srv/izywaretoolbar/5/apploader.js
required by taskrunner
* use the standard
mship izywaretoolbar/5/bootstrap/build;
- 55000002: clone izywaretoolbar/autocloudsync:api/ping to izywaretoolbar/5/autocloudsync:api/ping
- 55000001: apps/devicemanager/5/dashboard - add ability to set bucketId from UI
V5.4
- 54000008: Update language collateral in manifest.json
- 54000007: Update screenshots
- 54000006: Fix Use of permissions issue with web store
- 54000005: utilize chain operations for extension tests
* this will bring the tests on par with dashboard application
- 54000004: refactor izywaretoolbar/test/run.js and replace assertion library
- 54000003: migrate izyware/extensions to izywaretoolbar/5/extension/api
- 54000002: migrate tests to extension/chrome and reference in package.json
npm run test
- 54000001: fork
5/extension/chrome
./ldo.sh mship izywaretoolbar/5/extension/chrome/build
npm run test
V5.3
- 530006: add deviceextension.run
- 530002: izyware/extensions - fix bug where context is undefined.
- 530001: clone "viewer/view" from "viewer/top" for compatibility with modern shells
- migrate apps/extensionmanager/dashboard to apps/devicemanager/5/dashboard
V5.2
- Introduce
deviceextension.query
- add auto tagging in izyware.tag_idtoken post activation
* userid is set only when idtoken has not already been registered in the cloud.
- add message for successful installation to top of the page
- add
deviceextension.activate
, deviceextension.querystate
- migrate
storeinstaller
and izywaretoolbar/debug
to izywaretoolbar/5/dashboard
(see also notes section)
V5
- Introduce legacy 'browserextension.query'
- Add izyware/extensions:chainprocessor
V <= 5
node cli.js method chain chain.action "//inline/izywaretoolbar/test:run"
- improve izywaretoolbar/autocloudsync/api/ping to
* use better signature
* pass in data to the client for calibration
* added two sample calibration libraries (test1, test2)
- updated izywaretoolbar/autocloudsync/api/ping to log pings in the device database
- update UI for customers. default to readonly for now to prevent people from accidentlly turning on the debug mode
- storeinstaller (Wed, 13 Jun 2018)
* remove chrome.webstore.install since it is deprecated starting with chrome 71
- created new app 'Browser Extension' to capture the
* installation of the extenstion
* status, and control panel for the extension
- add chain processing to make programming easier
- Update the tool bar to the new UI LESS managed from one of the tabs
* less intrusive
* easier to build good UI
* Sometimes it is easy to get lost between a lot of open windows, contexts.
- https://izyware.com/chrome_extension.js needs to get updated to allow:
* Making the requests through the extension system. This will solve the cross-domain issues
* The payload needs to get put in directly so that it comes from the same domain
* The contentscript and UI into the webapge is problematic and flawed:
* content policy origin may block it
* The UI gets affected by the page
* Focus group found that it is not liked by customers
Do not draw the izywaretoolbar/contentscript* until it has been made visible
- on the izywaretoolbar/star page, fonts get bigger on https://www.google.com/intl/en/about/main/forbes-pichai-machine-learning/
- update collaterial.
- republish
Izyware Chrome extension page: https://chrome.google.com/webstore/detail/izyware-micro-apps-button/fbmkbppohioffpdpofcinmbmipaehgaa
izycloud deployment engine: https://izyware.com/help/article/izyware-deployment-engine
chrome store: https://chrome.google.com/webstore/detail/izyware-micro-apps-button/fbmkbppohioffpdpofcinmbmipaehgaa
chromeinlinelink: https://developer.chrome.com/webstore/inline_installation