@tapfiliate/tapfiliate-js 1.0.3 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -1
- package/dist/index.cjs +39 -13
- package/dist/index.d.ts +88 -5
- package/dist/index.mjs +39 -13
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -24,7 +24,7 @@ Import and initialize your tracking using the init function. Get your account id
|
|
|
24
24
|
|
|
25
25
|
`Tap.init(accountId);`
|
|
26
26
|
|
|
27
|
-
The init function will add the Tapfiliate script to your
|
|
27
|
+
The init function will add the Tapfiliate script to your website's head tag. This is needed for you to be able to use the rest of the Tap functions.
|
|
28
28
|
|
|
29
29
|
## Test your integration
|
|
30
30
|
|
|
@@ -67,6 +67,16 @@ To make the initialization easier we added the init function. Use Tap.init to in
|
|
|
67
67
|
|
|
68
68
|
## Changelog
|
|
69
69
|
|
|
70
|
+
### 1.1.1
|
|
71
|
+
|
|
72
|
+
- `Tap.init` keeps reporting the integration as `npm-module` when you pass your own create options; before, passing any create options dropped it.
|
|
73
|
+
|
|
74
|
+
### 1.1.0
|
|
75
|
+
|
|
76
|
+
- Calls made before `Tap.init` are no longer lost: they wait in a queue and run right after `init`. Before, `Tap.conversion(...)` called too early threw `window.__tap is not a function`.
|
|
77
|
+
- Safe in server-side rendering: on the server (no `window`), `Tap.init` and all other methods do nothing instead of throwing. Tracking happens when the page runs in the browser.
|
|
78
|
+
- TypeScript types for the tracking methods (`conversion`, `conversionMulti`, `customer`, `trial`, `lead`, `click`, `detect`) and their options, so your editor shows the arguments.
|
|
79
|
+
|
|
70
80
|
### 1.0.3
|
|
71
81
|
|
|
72
82
|
- Works with `require()` and in server-side rendering. The package now ships both CommonJS and ES module builds, which fixes `SyntaxError: Unexpected token 'export'` in Next.js and Node.js 18–20 ([#1](https://github.com/tapfiliate/tapfiliate-js/issues/1)).
|
package/dist/index.cjs
CHANGED
|
@@ -1,30 +1,59 @@
|
|
|
1
|
+
const scriptSrc = "https://script.tapfiliate.com/tapfiliate.js";
|
|
2
|
+
|
|
1
3
|
// Names that JavaScript itself and module loaders probe on any object. Forwarding them as tapfiliate.js
|
|
2
4
|
// methods made Tap look like a promise (`then`) or like a transpiled ES module (`__esModule`).
|
|
3
5
|
const notTapMethods = new Set(["then", "__esModule", "toJSON", "constructor"]);
|
|
4
6
|
|
|
7
|
+
// On the server (Next.js, Nuxt and other server-side rendering) there is no page to track: do nothing.
|
|
8
|
+
function inBrowser() {
|
|
9
|
+
return typeof window !== "undefined" && typeof document !== "undefined";
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
// The queue tapfiliate.js replays when it loads. Created on the first call, so calls made before init() are
|
|
13
|
+
// kept instead of failing. `npm` marks it as ours, unlike the queue of a Tapfiliate snippet already on the page.
|
|
14
|
+
function tapQueue() {
|
|
15
|
+
if (!window.__tap) {
|
|
16
|
+
window.TapfiliateObject = "__tap";
|
|
17
|
+
window.__tap = function() {
|
|
18
|
+
(window.__tap.q = window.__tap.q || []).push(arguments);
|
|
19
|
+
};
|
|
20
|
+
window.__tap.npm = true;
|
|
21
|
+
}
|
|
22
|
+
return window.__tap;
|
|
23
|
+
}
|
|
24
|
+
|
|
5
25
|
const handler = {
|
|
6
26
|
get: function(target, name) {
|
|
7
27
|
if (Object.prototype.hasOwnProperty.call(target, name)) return target[name];
|
|
8
28
|
if (typeof name !== "string" || notTapMethods.has(name)) return undefined;
|
|
9
29
|
return (...args) => {
|
|
10
|
-
|
|
30
|
+
if (!inBrowser()) return;
|
|
31
|
+
tapQueue()(name, ...args);
|
|
11
32
|
};
|
|
12
33
|
}
|
|
13
34
|
};
|
|
14
35
|
|
|
15
36
|
const target = {
|
|
16
|
-
init: (accountId, createOptions
|
|
17
|
-
if (
|
|
37
|
+
init: (accountId, createOptions, createCallback, detectOptions = {}, detectCallback) => {
|
|
38
|
+
if (!inBrowser()) return;
|
|
39
|
+
|
|
40
|
+
// Already set up: by a Tapfiliate snippet on the page, by an earlier init(), or tapfiliate.js has loaded
|
|
41
|
+
// (it replaces the queue with its own function).
|
|
42
|
+
if (window.__tap && (!window.__tap.npm || window.__tap.npmInitialized)) return;
|
|
18
43
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
44
|
+
var tap = tapQueue();
|
|
45
|
+
tap.npmInitialized = true;
|
|
46
|
+
|
|
47
|
+
// create and detect go before the calls queued earlier: tapfiliate.js replays the queue in order, and a
|
|
48
|
+
// conversion takes the account id from create.
|
|
49
|
+
tap.q = tap.q || [];
|
|
50
|
+
// `integration` tells Tapfiliate the account tracks through this package; it stays when other create options are
|
|
51
|
+
// passed (1.1.0 and earlier dropped it then), and an explicit `integration` still wins.
|
|
52
|
+
var options = Object.assign({ integration: "npm-module" }, createOptions);
|
|
53
|
+
tap.q.unshift(["create", accountId, options, createCallback], ["detect", detectOptions, detectCallback]);
|
|
25
54
|
|
|
26
55
|
var script = document.createElement("script");
|
|
27
|
-
script.src =
|
|
56
|
+
script.src = scriptSrc;
|
|
28
57
|
script.type = "text/javascript";
|
|
29
58
|
script.async = true;
|
|
30
59
|
|
|
@@ -35,9 +64,6 @@ const target = {
|
|
|
35
64
|
script.addEventListener("error", function() {
|
|
36
65
|
console.warn(`${this.src} failed to load.`);
|
|
37
66
|
});
|
|
38
|
-
|
|
39
|
-
window.__tap("create", accountId, createOptions, createCallback);
|
|
40
|
-
window.__tap("detect", detectOptions, detectCallback);
|
|
41
67
|
}
|
|
42
68
|
};
|
|
43
69
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,18 +1,101 @@
|
|
|
1
|
+
// Types for the tapfiliate.js methods documented at https://developers.tapfiliate.com/tracking/javascript.
|
|
2
|
+
// Options stay open (`[option: string]: unknown`) so a new tapfiliate.js option does not need a new release.
|
|
3
|
+
|
|
4
|
+
/** Callbacks fire only on success unless `always_callback: true` is passed; then they get `(error, result)`. */
|
|
5
|
+
export type TapCallback = (...args: any[]) => void;
|
|
6
|
+
|
|
7
|
+
export interface TapCallbackOptions {
|
|
8
|
+
/** Also call the callback when tracking fails, with the signature `(error, result)`. */
|
|
9
|
+
always_callback?: boolean;
|
|
10
|
+
[option: string]: unknown;
|
|
11
|
+
}
|
|
12
|
+
|
|
1
13
|
export interface TapCreateOptions {
|
|
2
14
|
integration?: string;
|
|
3
15
|
[option: string]: unknown;
|
|
4
16
|
}
|
|
5
17
|
|
|
18
|
+
export interface TapDetectOptions extends TapCallbackOptions {
|
|
19
|
+
/** Domain to set the cookie on, when visitors land on one subdomain and convert on another. */
|
|
20
|
+
cookie_domain?: string;
|
|
21
|
+
/** Referral code to use for this click instead of the one in the URL. */
|
|
22
|
+
referral_code?: string;
|
|
23
|
+
/** Query parameter that carries the referral code instead of `ref`, for example `via`. */
|
|
24
|
+
referral_code_param?: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** Extra data stored with a conversion or customer: up to 10 properties, no personal data. */
|
|
28
|
+
export type TapMetaData = Record<string, string | number | boolean>;
|
|
29
|
+
|
|
30
|
+
export interface TapConversionOptions extends TapCallbackOptions {
|
|
31
|
+
/** Your ID of the customer; with recurring commissions the conversion goes to the affiliate who referred them. */
|
|
32
|
+
customer_id?: string;
|
|
33
|
+
/** Three-letter ISO currency code, if it differs from the program currency. */
|
|
34
|
+
currency?: string;
|
|
35
|
+
/** Coupon codes used in the order. A coupon linked to an affiliate wins over the cookie. */
|
|
36
|
+
coupons?: string | string[];
|
|
37
|
+
meta_data?: TapMetaData;
|
|
38
|
+
/** Legacy: identifier of a program group. */
|
|
39
|
+
program_group?: string;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export interface TapCustomerOptions extends TapCallbackOptions {
|
|
43
|
+
coupons?: string | string[];
|
|
44
|
+
meta_data?: TapMetaData;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface TapCommission {
|
|
48
|
+
/** The part of the order amount for this commission. */
|
|
49
|
+
sub_amount: number;
|
|
50
|
+
/** Identifier of the commission type. */
|
|
51
|
+
commission_type: string;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** A referral code, or an asset ID and source ID. */
|
|
55
|
+
export interface TapTrackingParameters {
|
|
56
|
+
referral_code?: string;
|
|
57
|
+
asset_id?: string;
|
|
58
|
+
source_id?: string;
|
|
59
|
+
}
|
|
60
|
+
|
|
6
61
|
export interface Tap {
|
|
7
|
-
/**
|
|
62
|
+
/**
|
|
63
|
+
* Loads tapfiliate.js once, then runs `create` and `detect`. Calls made before `init` wait in a queue and run
|
|
64
|
+
* after it. On the server (no `window`) it does nothing, as do all other methods.
|
|
65
|
+
*/
|
|
8
66
|
init(
|
|
9
67
|
accountId: string,
|
|
10
68
|
createOptions?: TapCreateOptions,
|
|
11
|
-
createCallback?:
|
|
12
|
-
detectOptions?:
|
|
13
|
-
detectCallback?:
|
|
69
|
+
createCallback?: TapCallback,
|
|
70
|
+
detectOptions?: TapDetectOptions,
|
|
71
|
+
detectCallback?: TapCallback
|
|
72
|
+
): void;
|
|
73
|
+
/** Records a click if the URL carries affiliate tracking parameters. `init` already calls it. */
|
|
74
|
+
detect(options?: TapDetectOptions, callback?: TapCallback): void;
|
|
75
|
+
/** Tracks a conversion, usually a purchase. A second conversion with the same `externalId` is not tracked. */
|
|
76
|
+
conversion(
|
|
77
|
+
externalId: string,
|
|
78
|
+
amount?: number | null,
|
|
79
|
+
options?: TapConversionOptions,
|
|
80
|
+
commissionType?: string | null,
|
|
81
|
+
callback?: TapCallback
|
|
82
|
+
): void;
|
|
83
|
+
/** Tracks one conversion with several commissions. */
|
|
84
|
+
conversionMulti(
|
|
85
|
+
externalId: string,
|
|
86
|
+
options: TapConversionOptions,
|
|
87
|
+
commissions: TapCommission[],
|
|
88
|
+
callback?: TapCallback
|
|
14
89
|
): void;
|
|
15
|
-
/**
|
|
90
|
+
/** Tracks a referred customer at sign-up, before they pay. */
|
|
91
|
+
customer(customerId: string, options?: TapCustomerOptions, callback?: TapCallback): void;
|
|
92
|
+
/** Like `customer`, with the initial status trial. */
|
|
93
|
+
trial(customerId: string, options?: TapCustomerOptions, callback?: TapCallback): void;
|
|
94
|
+
/** Like `customer`, with the initial status lead. */
|
|
95
|
+
lead(customerId: string, options?: TapCustomerOptions, callback?: TapCallback): void;
|
|
96
|
+
/** Records a click from tracking parameters you pass explicitly. For standard setups use `detect`. */
|
|
97
|
+
click(trackingParameters: TapTrackingParameters, options?: TapCallbackOptions, callback?: TapCallback): void;
|
|
98
|
+
/** Any other tapfiliate.js method is forwarded as is. */
|
|
16
99
|
[method: string]: (...args: any[]) => void;
|
|
17
100
|
}
|
|
18
101
|
|
package/dist/index.mjs
CHANGED
|
@@ -1,30 +1,59 @@
|
|
|
1
|
+
const scriptSrc = "https://script.tapfiliate.com/tapfiliate.js";
|
|
2
|
+
|
|
1
3
|
// Names that JavaScript itself and module loaders probe on any object. Forwarding them as tapfiliate.js
|
|
2
4
|
// methods made Tap look like a promise (`then`) or like a transpiled ES module (`__esModule`).
|
|
3
5
|
const notTapMethods = new Set(["then", "__esModule", "toJSON", "constructor"]);
|
|
4
6
|
|
|
7
|
+
// On the server (Next.js, Nuxt and other server-side rendering) there is no page to track: do nothing.
|
|
8
|
+
function inBrowser() {
|
|
9
|
+
return typeof window !== "undefined" && typeof document !== "undefined";
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
// The queue tapfiliate.js replays when it loads. Created on the first call, so calls made before init() are
|
|
13
|
+
// kept instead of failing. `npm` marks it as ours, unlike the queue of a Tapfiliate snippet already on the page.
|
|
14
|
+
function tapQueue() {
|
|
15
|
+
if (!window.__tap) {
|
|
16
|
+
window.TapfiliateObject = "__tap";
|
|
17
|
+
window.__tap = function() {
|
|
18
|
+
(window.__tap.q = window.__tap.q || []).push(arguments);
|
|
19
|
+
};
|
|
20
|
+
window.__tap.npm = true;
|
|
21
|
+
}
|
|
22
|
+
return window.__tap;
|
|
23
|
+
}
|
|
24
|
+
|
|
5
25
|
const handler = {
|
|
6
26
|
get: function(target, name) {
|
|
7
27
|
if (Object.prototype.hasOwnProperty.call(target, name)) return target[name];
|
|
8
28
|
if (typeof name !== "string" || notTapMethods.has(name)) return undefined;
|
|
9
29
|
return (...args) => {
|
|
10
|
-
|
|
30
|
+
if (!inBrowser()) return;
|
|
31
|
+
tapQueue()(name, ...args);
|
|
11
32
|
};
|
|
12
33
|
}
|
|
13
34
|
};
|
|
14
35
|
|
|
15
36
|
const target = {
|
|
16
|
-
init: (accountId, createOptions
|
|
17
|
-
if (
|
|
37
|
+
init: (accountId, createOptions, createCallback, detectOptions = {}, detectCallback) => {
|
|
38
|
+
if (!inBrowser()) return;
|
|
39
|
+
|
|
40
|
+
// Already set up: by a Tapfiliate snippet on the page, by an earlier init(), or tapfiliate.js has loaded
|
|
41
|
+
// (it replaces the queue with its own function).
|
|
42
|
+
if (window.__tap && (!window.__tap.npm || window.__tap.npmInitialized)) return;
|
|
18
43
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
44
|
+
var tap = tapQueue();
|
|
45
|
+
tap.npmInitialized = true;
|
|
46
|
+
|
|
47
|
+
// create and detect go before the calls queued earlier: tapfiliate.js replays the queue in order, and a
|
|
48
|
+
// conversion takes the account id from create.
|
|
49
|
+
tap.q = tap.q || [];
|
|
50
|
+
// `integration` tells Tapfiliate the account tracks through this package; it stays when other create options are
|
|
51
|
+
// passed (1.1.0 and earlier dropped it then), and an explicit `integration` still wins.
|
|
52
|
+
var options = Object.assign({ integration: "npm-module" }, createOptions);
|
|
53
|
+
tap.q.unshift(["create", accountId, options, createCallback], ["detect", detectOptions, detectCallback]);
|
|
25
54
|
|
|
26
55
|
var script = document.createElement("script");
|
|
27
|
-
script.src =
|
|
56
|
+
script.src = scriptSrc;
|
|
28
57
|
script.type = "text/javascript";
|
|
29
58
|
script.async = true;
|
|
30
59
|
|
|
@@ -35,9 +64,6 @@ const target = {
|
|
|
35
64
|
script.addEventListener("error", function() {
|
|
36
65
|
console.warn(`${this.src} failed to load.`);
|
|
37
66
|
});
|
|
38
|
-
|
|
39
|
-
window.__tap("create", accountId, createOptions, createCallback);
|
|
40
|
-
window.__tap("detect", detectOptions, detectCallback);
|
|
41
67
|
}
|
|
42
68
|
};
|
|
43
69
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tapfiliate/tapfiliate-js",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.1",
|
|
4
4
|
"description": "Simple wrapper for the Tapfiliate javascript integration library to help with implementation in modern frontend applications.",
|
|
5
5
|
"main": "./dist/index.cjs",
|
|
6
6
|
"module": "./dist/index.mjs",
|