Strigo SDK
An SDK that initiates and manages the in-app Strigo experience.
Getting Started
Usage
Include this snippet in the <head>
section of your web application (you can copy it directly from Strigo's administrative console, in the Account page, with webApiKey
and subdomain
included):
<script>
(function () {
var s = document.createElement("script");
s.id = "strigo-sdk";
s.type = "text/javascript";
s.async = true;
s.src = "https://cdn.jsdelivr.net/gh/strigo/strigo-sdk@master/dist/production/strigo.sdk.min.js";
s.setAttribute("data-web-api-key", "<webApiKey>");
s.setAttribute("data-subdomain", "<subdomain>");
s.setAttribute("data-layout-flavor", "dynamic");
var x = document.getElementsByTagName("script")[0];
x.parentNode.insertBefore(s, x);
})();
</script>
This will add the Strigo
SDK to your window
and call Strigo.init()
to initialize the script.
API
Get the user token
In order for Strigo
SDK to communicate properly with Strigo, a token must be retrieved for your end user.
This token represents the user and the permissions it has against Strigo.
This token can be retrieved using Strigo's API using a server-to-server means of communication.
Make sure to retrieve the token before calling Strigo.setup()
.
Setup
To start the Strigo experience, call setup
with the following parameters:
window.Strigo.setup({
email: "user@domain.com",
// The token you received from Strigo's API
token: {
token: "",
expiration: ""
},
version: "v0.2.3"
});
Send events
Strigo
SDK enables you to send dedicted events to Strigo
's exercises.
These events could solve challenges you have created on Strigo
's Lounge.
Triggering these events is usually done in par with a user action that solves a challenge.
The eventName
is configured on Strigo
's Lounge in the class template, when creating the challenge.
window.Strigo.sendEvent(eventName);
Listen to SDK changes
Strigo
SDK allows you to register to events, so you can be reactive to it.
For instance, if you want to make changes to your web app's UI based on the state of the Strigo Panel, you can listen to the strigo-opened
event - which the SDK will trigger whenever the Strigo.setup()
is called.
window.addEventListener("strigo-opened", () => {
// Your custom code here
// e.g : setButtonDisabled(true)
});
Shutdown
To shut down the Strigo academy, simply call:
window.Strigo.shutdown();
The sessionStorage
will be erased and the page will refresh.
Destroy
To completely destroy the Strigo academy, use:
window.Strigo.destroy();
The academy panel will be closed, sessionStorage
and localStorage
configuration will be erased.
Development
Local
For developing with your local services and SDK:
- Add
127.0.0.1 local.strigo.io
to your hosts file (/etc/hosts
) - Set your
IS_DEVELOPMENT
variable totrue
in the.env
file.
Working with the Strigo Chrome extension locally
To allow a smoother dev experience with ability to test your changes in our Chrome extension
you can direct your local dev server to also write your latest strigo.sdk.js
bundle
into the strigo-academy-chrome-extension scripts folder.
A new build of the extension is not required in that case since Chrome extensions invoke everything in the scripts
folder dynamically.
The only thing you might need in order tou test your changes is to refresh the page.
-- in case you don't see your changes in the CE - try to update the extension in the chrome://extensions
page.
To start the dev server with the extension-hot-reload, run:
npm run build start:extension
Working with the Strigo Chrome extension in prod
DISCLAIMER!
We are "temporarily" 🙄 using the dist/development/strigo.sdk.js
build for production as well!
So the actual version you upload as the "prod" version of things should be the development build
but with the IS_DEVELOPMENT variable set to false!
To build a "development" build with the IS_DEVELOPMENT flag set to false you can either run the start:extension
command,
but set your .env
file IS_DEVELOPMENT
var to false.
or
You can run a single "prod" build that will write the sdk script into the extension scripts folder,
with isDevelopment
flag set to false
:
npm run build:extension
Testing
Edit the .env
file to include SDK_HOSTING_PORT
as you like (7000 is the default port).
Then, just run:
npm start
It will bundle the script and styles, and watch for changes. The scripts will be served in:
http://localhost:SDK_HOSTING_PORT/strigo.sdk.js
http://localhost:SDK_HOSTING_PORT/styles/strigo.css
You can include the script and call it from your local app.
Build
Our built script is served directly from GitHub, so please handle it correctly
npm run build
Will bundle and minify both js
and css
files to dist/production
directory.
Release
We use a script to automatically advance versions based on semver.
Merging to master alone does not create a new GitHub release. To actually create a release, you must provide a prefix in the last merged commit of your branch in the form of [semver:patch|minor|major]
. Merging to master will then update the latest
release and create a new versioned release as well.
Serve
The files in the dist/production
directory can be fetched by the free CDN at JSDelivr.
- https://cdn.jsdelivr.net/gh/strigo/strigo-sdk@master/dist/production/strigo.sdk.min.js
- https://cdn.jsdelivr.net/gh/strigo/strigo-sdk@master/dist/production/styles/strigo.min.css
- https://cdn.jsdelivr.net/gh/strigo/strigo-sdk@master/dist/production/styles/strigo-widget.min.css
Development guideline
Script Mechanism
Strigo
can operate in one of the following ways:
Host
- the script that invokes thesetup
method and initiated page manipulationSUBSCRIBER
- the script that runs "underneath" inside the Iframe, and one can only send events to itsHOST
, using thesessionStorage
orlocalStorage
Init
The init
method determines the status of the SDK. If the SDK is already invoked session.isPanelOpen()
- the status of the SDK will be SUBSCRIBER
and it won't be able to run setup
.
Page manipulation
The setup
method clears the original page and creates 2 iframes, side by side:
- Strigo iframe - using the
token
andwebApiKey
provided. - Original webpage iframe - with the original page structure and content.
Storing data
The setup
method creates two storage sessions / types:
strigoConfig
- onlocalStorage
- represents the relevant data for the script initiation and operation.
Example:
{
"email": "hidday+strigo-user@strigo.io",
"initSite": {
"host": "strigo-demo.web.app",
"pathName": "/",
"href": "https://strigo-demo.web.app/",
"origin": "https://strigo-demo.web.app",
"search": "",
"params": {}
},
"token": {
"token": "RhrsHoc1bDcQagl7znXdg-7f4WKeLWa_99zZMj92zen",
"expiration": 1644512345678
},
"webApiKey": "zzzzzz",
"subDomain": "strigo.dev"
}
strigoSession
- onsessionStorage
- represents the data that's relevant to the current session / tab.
Example
{
"currentUrl": "https://strigo-demo.web.app/",
"isPanelOpen": true,
"isLoading": false,
"widgetFlavor": "iframe"
}
Code structure and tools
General notes
We try to keep the script as zero-dependency as possible, since it's a code that's intended to run inside your application.
Modules you can use
url
- url tools to parse and build urls.document
- document manipulation tools, for appending Iframes, CSS, other elements to the document.storage-utils
- a helper module to manage bothlocalStorage
andsessionStorage
.config
- the module that managesstrigoConfig
onlocalStorage
.session
- the module that managesstrigoSession
onsessionStorage
- data is relevant for every session (tab).
Contributions
Found a bug? Please file a PR!