@saasquatch/squatch-js 2.6.0-0 → 2.6.0-10

package/.github/workflows/static.yml

@@ -0,0 +1,89 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  # Write permissions are needed to push the built site to the gh-pages branch
+  contents: write
+  id-token: write
+  pull-requests: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      PR_PATH: pull/${{github.event.number}}
+
+    steps:
+      - name: Checkout
+        id: checkout
+        uses: actions/checkout@v3
+
+      - name: Comment on PR
+        if: github.ref != 'refs/heads/master'
+        id: preview-comment
+        uses: hasura/comment-progress@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "Starting deployment of docs preview ⏳..."
+
+      - name: Setup NodeJS
+        id: setup-node
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: package.json
+          cache: "npm"
+
+      - name: NPM Install
+        id: npm-ci
+        run: npm ci
+
+      - name: Build Docs
+        id: build-docs
+        run: npm run build:docs
+
+      - name: Deploy Master
+        if: github.ref == 'refs/heads/master'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+
+      - name: Deploy Preview
+        if: github.ref != 'refs/heads/master'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          destination_dir: ${{ env.PR_PATH }}
+
+      - name: Update preview comment
+        if: github.ref != 'refs/heads/master'
+        id: update-preview-comment
+        uses: hasura/comment-progress@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          repository: ${{ github.repository }}
+          number: ${{ github.event.number }}
+          id: deploy-preview
+          message: "A preview of ${{ github.event.after }} is uploaded and can be seen here:\n\n ✨ https://saasquatch.github.io/squatch-js/${{ env.PR_PATH }} ✨"

package/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- Added custom web-components `squatch-embed` and `squatch-popup` for easier widget rendering.
+- Support for additional namespacing of squatchjs
+
 ## [2.5.0] - 2023-05-16
 
 ### Removed

package/README.md

@@ -1,5 +1,21 @@
 # Referral SaaSquatch Javascript SDK
 
+- [Referral SaaSquatch Javascript SDK](#referral-saasquatch-javascript-sdk)
+  - [Install the library](#install-the-library)
+  - [Getting Started](#getting-started)
+  - [Data Only Operations](#data-only-operations)
+      - [Create/upsert users without loading a widget.](#createupsert-users-without-loading-a-widget)
+  - [Get Referral Cookie Code](#get-referral-cookie-code)
+  - [Install via NPM and Webpack (advanced)](#install-via-npm-and-webpack-advanced)
+  - [Component API:](#component-api)
+    - [`squatch-embed`](#squatch-embed)
+    - [`squatch-popup`](#squatch-popup)
+  - [Legacy](#legacy)
+    - [Rendering a widget via Widgets API](#rendering-a-widget-via-widgets-api)
+  - [Contributing](#contributing)
+  - [Support](#support)
+
+
 ## Install the library
 
 To integrate any SaaSquatch program to your website or web app, copy/paste this snippet of JavaScript above the `</head>` tag of your page:
@@ -18,85 +34,37 @@ Or load the library synchronously from our CDN:
 
 
 ## Getting Started
-The `init` function lets you configure your global squatch instance.
-
-Note: `engagementMedium` is required in the `squatch.widgets()` functions if you want to load the widget. Otherwise, Squatch.js will look for your portal settings and render the widget that's mapped to the URL where this snippet is included.
 
+Include either of the squatchjs generated web-components in your page's HTML to render your desired widget:
 ```html
-<script type="text/javascript">
-  squatch.ready(function() {
-
-    // Always call init
-    squatch.init({
-      tenantAlias: "YOUR_TENANT_ALIAS",     // String (required)
-    });
-  
-    squatch.widgets().upsertUser({
-      user: {                               // Object (required)
-        id: 'USER_ID',                      // String (required)
-        accountId: 'USER_ACCOUNT_ID',       // String (required)
-        email: 'USER_EMAIL',                // String (optional)
-        firstName: 'USER_FIRST_NAME',       // String (optional)
-        lastName: 'USER_LAST_NAME',         // String (optional)
-  
-        ...
-      },
-      engagementMedium: 'EMBED',                    // String (optional: POPUP, EMBED)
-      widgetType: 'p/PROGRAM-ID/w/referrerWidget',  // Update PROGRAM-ID
-      jwt: 'TOKEN'                                  // String (required by default, or disable Security in the portal)
+<!-- EMBED WIDGET -->
+<squatch-embed widget="WIDGET_TYPE"><!-- Widget is rendered here --></squatch-embed>
 
-    });
-  });
-</script>
+<!-- POPUP WIDGET -->
+<squatch-popup widget="WIDGET_TYPE"><!-- Widget is rendered here --></squatch-popup>
 ```
+For rendering widgets and API calls, squatchjs respects configurations set on the following:
+  - `window.squatchToken`: Signed JWT for calls to the SaaSquatch API -- [How to generate valid JWT Tokens](https://docs.saasquatch.com/topics/json-web-tokens#example-building-the-jwt)
+  - `window.squatchTenant`: SaaSquatch tenant alias
+  - `window.squatchConfig`: Additional configuration overrides (Optional)
+    - `debug`: Turn on console debugging (Default: `false`)
 
-### Declarative method for rendering widgets
-As opposed to the above method which requires some manual javascript, squatchjs includes the custom Web Components: `squatch-embed` and `squatch-popup` that can render embedded and popup widgets respectively.
-
-TODO: `display: inline` until squatchjs loads
+**Note**: If `window.squatchToken` is undefined, widgets will be rendered as [Instant Access widgets](https://docs.saasquatch.com/topics/widget-types#instant-access-widgets).
 
-```html
-<script type="text/javascript">
-  window.squatchToken = "TOKEN"
-  window.squatchTenant = "TENANT_ALIAS"
 
-  // Optional
-  window.squatchConfig = {
-    ... // Custom configuration settings
-  }
-</script>
 
-<squatch-embed widget="WIDGET_TYPE"><!-- Widget is rendered here --></squatch-embed>
-<squatch-popup widget="WIDGET_TYPE"><!-- Widget is rendered here --></squatch-popup>
-```
 
-#### `squatch-embed`
 
-- `widget`: Specifies the SaaSquatch `widgetType` identifier of the desired widget
-  - Required
-- `container`: A CSS selector for a container element to use as the parent of the widget's iframe. 
-  - Default: `null`
-  - Note, if no container is specified, the widget iframe will attach to the shadow DOM of `squatch-embed`.
+## Data Only Operations
 
 
-#### `squatch-popup`
-
-- `widget: string`: Specifies the SaaSquatch `widgetType` identifier of the desired widget
-  - Required
-- `show: boolean`: Whether to show the popup dialog on page load or not.
-  - Default: `false`
-## Data Only Operations
-You can create/upsert users without loading a widget.
+#### Create/upsert users without loading a widget.
 
 ```html
 <script type="text/javascript">
-  squatch.ready(function() {
-
-    // Always call init
-    squatch.init({
-      tenantAlias: "YOUR_TENANT_ALIAS"      // String (required)
-    });
+  // Assuming window.squatchTenant, and window.squatchToken are set
 
+  squatch.ready(function() {
     var user;
 
     squatch.api().upsertUser({
@@ -110,7 +78,6 @@ You can create/upsert users without loading a widget.
       },
       engagementMedium: 'EMBED',                    // String (optional: POPUP, EMBED)
       widgetType: 'p/PROGRAM-ID/w/referrerWidget',  // Update PROGRAM-ID
-      jwt: 'TOKEN'                                  // String (required)
     }).then(function(response) {
       user = response.user;
     }).catch(function(err){
@@ -132,10 +99,6 @@ You can also use the `api()` function to call the WidgetApi methods directly.
 <script type="text/javascript">
   squatch.ready(function(){
 
-    // Always call init
-    squatch.init({tenantAlias: 'YOUR_TENANT_ALIAS'});
-
-
     var element = document.getElementById('my_coupon');
 
     squatch.api().squatchReferralCookie().then(function(response) {
@@ -173,6 +136,71 @@ squatch.api().upsertUser({...});
 
 ```
 
+## Component API:
+
+### `squatch-embed`
+```html
+<squatch-embed widget="WIDGET_TYPE" [ container="#selector" | locale="en_US" ]>
+  <!-- Children of squatch-embed act as a loading state -->
+  Loading...
+</squatch-embed>
+```
+
+- `widget`: Specifies the SaaSquatch `widgetType` identifier of the desired widget
+  - Required
+  - Changing this attribute's value causes the widget to reload.
+- `container`: A CSS selector for a container element to use as the parent of the widget's iframe. 
+  - Default: `null`
+  - Note, if no container is specified, the widget iframe will attach to the shadow DOM of `squatch-embed`.
+- `locale`: Locale that determines the widget translation displayed. Should be of the form "xx_XX".
+  - Default: Browser's current locale
+  - Changing this attribute's value causes the widget to reload.
+
+### `squatch-popup`
+```html
+<squatch-embed widget="WIDGET_TYPE" [ open | container="#selector" | locale="en_US" ]>
+  <!-- Clicking a child of squatch-popup opens the popup -->
+  <button>Click me to open</button> 
+</squatch-embed>
+```
+
+- `widget: string`: Specifies the SaaSquatch `widgetType` identifier of the desired widget
+  - Required
+- `open: boolean`: Whether to the popup is open when loaded into the page
+  - Default: `false`
+- `container`: A CSS selector for a container element to use as the parent of the widget's iframe. 
+  - Default: `null`
+  - Note, if no container is specified, the widget iframe will attach to the shadow DOM of `squatch-embed`.
+- `locale`: Locale that determines the widget translation displayed. Should be of the form "xx_XX".
+  - Default: Browser's current locale
+  - Changing this attribute's value causes the widget to reload.
+
+## Legacy
+
+### Rendering a widget via Widgets API
+Note: `engagementMedium` is required in the `squatch.widgets()` functions if you want to load the widget. Otherwise, squatch.js will look for your portal settings and render the widget that's mapped to the URL where this snippet is included.
+
+```html
+<script type="text/javascript">
+  squatch.ready(function() {
+
+    squatch.widgets().upsertUser({
+      user: {                               // Object (required)
+        id: 'USER_ID',                      // String (required)
+        accountId: 'USER_ACCOUNT_ID',       // String (required)
+        email: 'USER_EMAIL',                // String (optional)
+        firstName: 'USER_FIRST_NAME',       // String (optional)
+        lastName: 'USER_LAST_NAME',         // String (optional)
+  
+        ...
+      },
+      engagementMedium: 'EMBED',                    // String (optional: POPUP, EMBED)
+      widgetType: 'p/PROGRAM-ID/w/referrerWidget',  // Update PROGRAM-ID
+    });
+  });
+</script>
+```
+
 ## Contributing
 This is an open source project! If you are interested in contributing please look at [contributing guidelines](CONTRIBUTING.md) first.