Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/saasquatch/squatch-js
🌐 The official SaaSquatch Javascript Web/Browser SDK
https://github.com/saasquatch/squatch-js
javascript referrals
Last synced: 2 months ago
JSON representation
🌐 The official SaaSquatch Javascript Web/Browser SDK
- Host: GitHub
- URL: https://github.com/saasquatch/squatch-js
- Owner: saasquatch
- License: mit
- Created: 2016-08-10T19:10:57.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-07-12T21:24:21.000Z (6 months ago)
- Last Synced: 2024-10-14T13:37:27.112Z (3 months ago)
- Topics: javascript, referrals
- Language: TypeScript
- Homepage: https://docs.referralsaasquatch.com/developer/squatchjs/
- Size: 8.36 MB
- Stars: 5
- Watchers: 12
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# 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 `` tag of your page:
```html
!(function (a, b) {
a("squatch", "https://fast.ssqt.io/squatch-js@2", b);
})(function (a, b, c) {
var d, e, f;
(c["_" + a] = {}),
(c[a] = {}),
(c[a].ready = function (b) {
c["_" + a].ready = c["_" + a].ready || [];
c["_" + a].ready.push(b);
}),
(e = document.createElement("script")),
(e.async = 1),
(e.src = b),
(f = document.getElementsByTagName("script")[0]),
f.parentNode.insertBefore(e, f);
}, this);
```
Or load the library synchronously from our CDN:
```html
```
## Getting Started
Include either of the squatchjs generated web-components in your page's HTML to render your desired widget:
```html
```
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`)
- `window.squatchOnReady`: Declarative on ready function to be run when the squatch-js module has finished loading
```html
window.squatchOnReady = () => {
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
});
}
```
**Note**: If `window.squatchToken` is undefined, widgets will be rendered as [Instant Access widgets](https://docs.saasquatch.com/topics/widget-types#instant-access-widgets).
## Data Only Operations
#### Create/upsert users without loading a widget.
```html
// Assuming window.squatchTenant, and window.squatchToken are set
squatch.ready(function() {
var user;
squatch.api().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
}).then(function(response) {
user = response.user;
}).catch(function(err){
console.log(err);
});
// autofill
var element = document.getElementById('my_coupon');
element.value = user.referredBy.code;
});
```
## Get Referral Cookie Code
You can also use the `api()` function to call the WidgetApi methods directly.
```html
squatch.ready(function () {
var element = document.getElementById("my_coupon");
squatch
.api()
.squatchReferralCookie()
.then(function (response) {
/* `response.codes` looks like `{"program_id":"NEWCO", "friend_program":"BOB"}` */
element.value = response.codes["program-id"];
});
});
```
Want more control? Visit our [guide](https://github.com/saasquatch/squatch-js/blob/master/docs/docs.md).
## Install via NPM and Webpack (advanced)
Squatch.js can also be installed via NPM and bundled into your application with Webpack.
```ssh
# via npm
$ npm install @saasquatch/squatch-js
```
```js
import * as squatch from "@saasquatch/squatch-js";
// Always call init
squatch.init({
tenantAlias: "YOUR_TENANT_ALIAS" // String (required)
});
// Don't need to wait for .ready when importing via NPM/Webpack
squatch.api().upsertUser({...});
```
## Component API:
### `squatch-embed`
```html
Loading...
```
- `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
Click me to open
```
- `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
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
});
});
```
## Contributing
This is an open source project! If you are interested in contributing please look at [contributing guidelines](CONTRIBUTING.md) first.
## Support
Shoot us an email at [[email protected]](mailto:[email protected]) if you need help!