@shware/analytics 0.1.17 → 0.1.18
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/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.mjs.map +1 -1
- package/dist/next/index.cjs +102 -5
- package/dist/next/index.cjs.map +1 -1
- package/dist/next/index.d.cts +21 -2
- package/dist/next/index.d.ts +21 -2
- package/dist/next/index.mjs +89 -4
- package/dist/next/index.mjs.map +1 -1
- package/dist/react-router/index.cjs +91 -4
- package/dist/react-router/index.cjs.map +1 -1
- package/dist/react-router/index.d.cts +21 -2
- package/dist/react-router/index.d.ts +21 -2
- package/dist/react-router/index.mjs +88 -3
- package/dist/react-router/index.mjs.map +1 -1
- package/dist/schema/index.d.cts +8 -8
- package/dist/schema/index.d.ts +8 -8
- package/dist/setup/index.cjs.map +1 -1
- package/dist/setup/index.d.cts +3 -1
- package/dist/setup/index.d.ts +3 -1
- package/dist/setup/index.mjs.map +1 -1
- package/dist/track/fbq.cjs +143 -0
- package/dist/track/fbq.cjs.map +1 -0
- package/dist/track/fbq.d.cts +278 -0
- package/dist/track/fbq.d.ts +278 -0
- package/dist/track/fbq.mjs +117 -0
- package/dist/track/fbq.mjs.map +1 -0
- package/dist/track/{ga.cjs → gtag.cjs} +5 -5
- package/dist/track/gtag.cjs.map +1 -0
- package/dist/track/gtag.d.cts +463 -0
- package/dist/track/gtag.d.ts +463 -0
- package/dist/track/{ga.mjs → gtag.mjs} +2 -2
- package/dist/track/gtag.mjs.map +1 -0
- package/dist/track/index.cjs.map +1 -1
- package/dist/track/index.d.cts +3 -2
- package/dist/track/index.d.ts +3 -2
- package/dist/track/index.mjs.map +1 -1
- package/dist/{types/index.cjs → track/types.cjs} +2 -2
- package/dist/track/types.cjs.map +1 -0
- package/dist/track/types.d.cts +87 -0
- package/dist/track/types.d.ts +87 -0
- package/dist/track/types.mjs +1 -0
- package/dist/visitor/index.cjs.map +1 -1
- package/dist/visitor/index.d.cts +1 -1
- package/dist/visitor/index.d.ts +1 -1
- package/dist/visitor/index.mjs.map +1 -1
- package/dist/visitor/types.cjs +19 -0
- package/dist/visitor/types.cjs.map +1 -0
- package/dist/visitor/types.d.cts +16 -0
- package/dist/visitor/types.d.ts +16 -0
- package/dist/visitor/types.mjs +1 -0
- package/dist/visitor/types.mjs.map +1 -0
- package/dist/web/index.cjs.map +1 -1
- package/dist/web/index.d.cts +2 -1
- package/dist/web/index.d.ts +2 -1
- package/dist/web/index.mjs.map +1 -1
- package/package.json +1 -1
- package/dist/track/ga.cjs.map +0 -1
- package/dist/track/ga.d.cts +0 -4
- package/dist/track/ga.d.ts +0 -4
- package/dist/track/ga.mjs.map +0 -1
- package/dist/types/index.cjs.map +0 -1
- package/dist/types/index.d.cts +0 -327
- package/dist/types/index.d.ts +0 -327
- package/dist/types/index.mjs +0 -1
- /package/dist/{types/index.mjs.map → track/types.mjs.map} +0 -0
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
import { EventName, TrackName, TrackProperties } from './types.cjs';
|
|
2
|
+
import './gtag.cjs';
|
|
3
|
+
|
|
4
|
+
type Content = {
|
|
5
|
+
id: string;
|
|
6
|
+
quantity: number;
|
|
7
|
+
[key: string]: unknown;
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* reference: https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching
|
|
11
|
+
* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
|
|
12
|
+
*/
|
|
13
|
+
type MatchingParameters = {
|
|
14
|
+
/** Email: Unhashed lowercase or hashed SHA-256 */
|
|
15
|
+
em?: string;
|
|
16
|
+
/** First Name: Lowercase letters */
|
|
17
|
+
fn?: string;
|
|
18
|
+
/** Last Name: Lowercase letters */
|
|
19
|
+
ln?: string;
|
|
20
|
+
/** Phone Number: Digits only including country code and area code */
|
|
21
|
+
ph?: string;
|
|
22
|
+
/**
|
|
23
|
+
* External ID: Any unique ID from the advertiser, such as loyalty membership ID, user ID, and
|
|
24
|
+
* external cookie ID.
|
|
25
|
+
*/
|
|
26
|
+
external_id?: string;
|
|
27
|
+
/** Gender: Single lowercase letter, f or m, if unknown, leave blank */
|
|
28
|
+
ge?: 'f' | 'm' | '';
|
|
29
|
+
/** Birthdate: Digits only with birth year, month, then day, YYYYMMDD */
|
|
30
|
+
db?: number;
|
|
31
|
+
/** City: Lowercase with any spaces removed, e.g. "menlopark" */
|
|
32
|
+
ct?: string;
|
|
33
|
+
/** State or Province: Lowercase two-letter state or province code, e.g. "ca" */
|
|
34
|
+
st?: string;
|
|
35
|
+
/** Zip or Postal Code: String */
|
|
36
|
+
zp?: string;
|
|
37
|
+
/** Country: Lowercase two-letter country code, e.g. "us" */
|
|
38
|
+
country?: string;
|
|
39
|
+
/** Client IP Address: Do not hash. */
|
|
40
|
+
client_ip_address?: string;
|
|
41
|
+
/** Client User Agent: Do not hash. */
|
|
42
|
+
client_user_agent?: string;
|
|
43
|
+
/**
|
|
44
|
+
* Click ID: Do not hash.
|
|
45
|
+
* The Facebook click ID value is stored in the _fbc browser cookie under your domain. See
|
|
46
|
+
* Managing fbc and fbp Parameters for how to get this value or generate this value from a fbclid
|
|
47
|
+
* query parameter.
|
|
48
|
+
*
|
|
49
|
+
* The format is fb.${subdomain_index}.${creation_time}.${fbclid}.
|
|
50
|
+
*/
|
|
51
|
+
fbc?: string;
|
|
52
|
+
/**
|
|
53
|
+
* Browser ID: Do not hash.
|
|
54
|
+
* The Facebook browser ID value is stored in the _fbp browser cookie under your domain. See
|
|
55
|
+
* Managing fbc and fbp Parameters for how to get this value.
|
|
56
|
+
*
|
|
57
|
+
* The format is fb.${subdomain_index}.${creation_time}.${random_number}.
|
|
58
|
+
*/
|
|
59
|
+
fbp?: string;
|
|
60
|
+
/**
|
|
61
|
+
* Subscription ID: Do not hash.
|
|
62
|
+
* The subscription ID for the user in this transaction; it is similar to the order ID for an
|
|
63
|
+
* individual product.
|
|
64
|
+
*/
|
|
65
|
+
subscription_id?: string;
|
|
66
|
+
/**
|
|
67
|
+
* Facebook Login ID: Do not hash.
|
|
68
|
+
* The ID issued by Meta when a person first logs into an instance of an app. This is also known
|
|
69
|
+
* as App-Scoped ID.
|
|
70
|
+
*/
|
|
71
|
+
fb_login_id?: number;
|
|
72
|
+
/**
|
|
73
|
+
* Lead ID: Do not hash.
|
|
74
|
+
* The ID associated with a lead generated by [Meta's Lead Ads](https://developers.facebook.com/docs/marketing-api/guides/lead-ads).
|
|
75
|
+
*/
|
|
76
|
+
lead_id?: number;
|
|
77
|
+
/**
|
|
78
|
+
* Install ID: Do not hash.
|
|
79
|
+
* Your install ID. This field represents unique application installation instances.
|
|
80
|
+
* Note: This parameter is for app events only.
|
|
81
|
+
*/
|
|
82
|
+
anon_id?: string;
|
|
83
|
+
/**
|
|
84
|
+
* Your mobile advertiser ID, the advertising ID from an Android device or the Advertising
|
|
85
|
+
* Identifier (IDFA) from an Apple device.
|
|
86
|
+
*/
|
|
87
|
+
madid?: string;
|
|
88
|
+
/**
|
|
89
|
+
* Page ID: Do not hash.
|
|
90
|
+
* Your Page ID. Specifies the page ID associated with the event. Use the Facebook page ID of the
|
|
91
|
+
* page associated with the bot.
|
|
92
|
+
*/
|
|
93
|
+
page_id?: string;
|
|
94
|
+
/**
|
|
95
|
+
* Page Scoped User ID: Do not hash.
|
|
96
|
+
* Specifies the page-scoped user ID associated with the messenger bot that logs the event. Use
|
|
97
|
+
* the page-scoped user ID provided to your webhook.
|
|
98
|
+
*/
|
|
99
|
+
page_scoped_user_id?: string;
|
|
100
|
+
/**
|
|
101
|
+
* Do not hash.
|
|
102
|
+
* Click ID generated by Meta for ads that click to WhatsApp.
|
|
103
|
+
*/
|
|
104
|
+
ctwa_clid?: string;
|
|
105
|
+
/**
|
|
106
|
+
* Do not hash.
|
|
107
|
+
* Instagram Account ID that is associated with the business.
|
|
108
|
+
*/
|
|
109
|
+
ig_account_id?: string;
|
|
110
|
+
/**
|
|
111
|
+
* Do not hash.
|
|
112
|
+
* Users who interact with Instagram are identified by Instagram-Scoped User IDs (IGSID). IGSID
|
|
113
|
+
* can be obtained from this webhook.
|
|
114
|
+
*/
|
|
115
|
+
ig_sid?: string;
|
|
116
|
+
};
|
|
117
|
+
/**
|
|
118
|
+
* You can include the following predefined object properties with any custom events, and any
|
|
119
|
+
* standard events that support them. Format your parameter object data using JSON. Learn more about
|
|
120
|
+
* event parameters with Blueprint.
|
|
121
|
+
*/
|
|
122
|
+
type ObjectProperties = {
|
|
123
|
+
content_category?: string;
|
|
124
|
+
content_ids?: string[];
|
|
125
|
+
content_name?: string;
|
|
126
|
+
/**
|
|
127
|
+
* Either product or product_group based on the content_ids or contents being passed. If the IDs
|
|
128
|
+
* being passed in content_ids or contents parameter are IDs of products, then the value should be
|
|
129
|
+
* product. If product group IDs are being passed, then the value should be product_group.
|
|
130
|
+
*
|
|
131
|
+
* If no content_type is provided, Meta will match the event to every item that has the same ID,
|
|
132
|
+
* independent of its type.
|
|
133
|
+
*/
|
|
134
|
+
content_type?: 'product' | 'product_group' | (string & {});
|
|
135
|
+
contents?: Content[];
|
|
136
|
+
delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
|
|
137
|
+
currency?: string;
|
|
138
|
+
num_items?: number;
|
|
139
|
+
predicted_ltv?: number;
|
|
140
|
+
search_string?: string;
|
|
141
|
+
/** Used with the CompleteRegistration event, to show the status of the registration. */
|
|
142
|
+
status?: boolean;
|
|
143
|
+
value?: number;
|
|
144
|
+
};
|
|
145
|
+
/**
|
|
146
|
+
* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/payload-helper
|
|
147
|
+
*/
|
|
148
|
+
type StandardEvents = {
|
|
149
|
+
AddPaymentInfo: {
|
|
150
|
+
content_ids?: string[];
|
|
151
|
+
contents?: Content[];
|
|
152
|
+
currency?: string;
|
|
153
|
+
value?: number;
|
|
154
|
+
};
|
|
155
|
+
AddToCart: {
|
|
156
|
+
content_ids?: string[];
|
|
157
|
+
content_type?: string;
|
|
158
|
+
contents?: Content[];
|
|
159
|
+
currency?: string;
|
|
160
|
+
value?: number;
|
|
161
|
+
};
|
|
162
|
+
AddToWishlist: {
|
|
163
|
+
content_ids?: string[];
|
|
164
|
+
contents?: Content[];
|
|
165
|
+
currency?: string;
|
|
166
|
+
value?: number;
|
|
167
|
+
};
|
|
168
|
+
CompleteRegistration: {
|
|
169
|
+
currency?: string;
|
|
170
|
+
value?: number;
|
|
171
|
+
method?: string;
|
|
172
|
+
};
|
|
173
|
+
Contact: {};
|
|
174
|
+
CustomizeProduct: {};
|
|
175
|
+
Donate: {};
|
|
176
|
+
FindLocation: {};
|
|
177
|
+
InitiateCheckout: {
|
|
178
|
+
content_ids?: string[];
|
|
179
|
+
contents?: Content[];
|
|
180
|
+
currency?: string;
|
|
181
|
+
num_items?: number;
|
|
182
|
+
value?: number;
|
|
183
|
+
};
|
|
184
|
+
Lead: {
|
|
185
|
+
currency?: string;
|
|
186
|
+
value?: number;
|
|
187
|
+
};
|
|
188
|
+
Purchase: {
|
|
189
|
+
content_ids?: string[];
|
|
190
|
+
content_type?: string;
|
|
191
|
+
contents?: Content[];
|
|
192
|
+
currency: string;
|
|
193
|
+
num_items?: number;
|
|
194
|
+
value: number;
|
|
195
|
+
};
|
|
196
|
+
Schedule: {};
|
|
197
|
+
Search: {
|
|
198
|
+
content_ids?: string[];
|
|
199
|
+
content_type?: string;
|
|
200
|
+
contents?: Content[];
|
|
201
|
+
currency?: string;
|
|
202
|
+
search_string?: string;
|
|
203
|
+
value?: number;
|
|
204
|
+
};
|
|
205
|
+
StartTrial: {
|
|
206
|
+
currency?: string;
|
|
207
|
+
predicted_ltv?: number;
|
|
208
|
+
value?: number;
|
|
209
|
+
};
|
|
210
|
+
SubmitApplication: {};
|
|
211
|
+
Subscribe: {
|
|
212
|
+
currency?: string;
|
|
213
|
+
predicted_ltv?: number;
|
|
214
|
+
value?: number;
|
|
215
|
+
};
|
|
216
|
+
ViewContent: {
|
|
217
|
+
content_ids?: string[];
|
|
218
|
+
content_type?: string;
|
|
219
|
+
contents?: Content[];
|
|
220
|
+
currency?: string;
|
|
221
|
+
value?: number;
|
|
222
|
+
};
|
|
223
|
+
};
|
|
224
|
+
type JSONValue = null | string | number | boolean | Array<JSONValue> | {
|
|
225
|
+
[value: string]: JSONValue;
|
|
226
|
+
};
|
|
227
|
+
type PixelId = `${number}`;
|
|
228
|
+
/**
|
|
229
|
+
* reference: https://developers.facebook.com/docs/meta-pixel/reference#standard-events
|
|
230
|
+
*
|
|
231
|
+
* We determine if events are identical based on their ID and name. So, for an event to be deduplicated:
|
|
232
|
+
* - In corresponding events, a Meta Pixel's eventID must match the Conversion API's event_id.
|
|
233
|
+
* - In corresponding events, a Meta Pixel's event must match the Conversion API's event_name.
|
|
234
|
+
*
|
|
235
|
+
* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
|
|
236
|
+
*/
|
|
237
|
+
interface Fbq {
|
|
238
|
+
/**
|
|
239
|
+
* reference: https://stackoverflow.com/questions/62304291/sending-user-data-parameters-via-pixel
|
|
240
|
+
*
|
|
241
|
+
* Call init the normal default way first:
|
|
242
|
+
* `fbq('init', 'XXXXX')`
|
|
243
|
+
*
|
|
244
|
+
* And at a later point in time, when you have obtained additional user data, you can call init
|
|
245
|
+
* again basically enriching the already running fbq instance with additional data:
|
|
246
|
+
* `fbq('init', 'XXXXX', { external_id: 1234, em: 'abc@abc.com' } )`
|
|
247
|
+
*
|
|
248
|
+
* Only caveat is that you have to send an event after this additional init call, otherwise the
|
|
249
|
+
* provided data will not be sent to Facebook.
|
|
250
|
+
*/
|
|
251
|
+
fbq(type: 'init', pixelId: PixelId, parameters?: MatchingParameters): void;
|
|
252
|
+
/** Enable Manual Only mode. (value = false) */
|
|
253
|
+
fbq(type: 'set', key: 'autoConfig', value: boolean, pixelId: PixelId): void;
|
|
254
|
+
fbq<T extends keyof StandardEvents>(type: 'track', event: T, properties?: StandardEvents[T] & ObjectProperties, options?: {
|
|
255
|
+
eventID?: string;
|
|
256
|
+
}): void;
|
|
257
|
+
fbq(type: 'trackCustom', event: string, properties?: Record<string, JSONValue> & ObjectProperties, options?: {
|
|
258
|
+
eventID?: string;
|
|
259
|
+
}): void;
|
|
260
|
+
/** https://developers.facebook.com/docs/meta-pixel/guides/track-multiple-events/ */
|
|
261
|
+
fbq<T extends keyof StandardEvents>(type: 'trackSingle', pixelId: PixelId, event: T, properties?: StandardEvents[T] & ObjectProperties, options?: {
|
|
262
|
+
eventID?: string;
|
|
263
|
+
}): void;
|
|
264
|
+
/** https://developers.facebook.com/docs/meta-pixel/guides/track-multiple-events/ */
|
|
265
|
+
fbq(type: 'trackSingleCustom', pixelId: PixelId, event: string, properties?: Record<string, JSONValue> & ObjectProperties, options?: {
|
|
266
|
+
eventID?: string;
|
|
267
|
+
}): void;
|
|
268
|
+
}
|
|
269
|
+
/**
|
|
270
|
+
* Please download this CSV filefor examples of properly normalized and hashed data for the
|
|
271
|
+
* parameters below.
|
|
272
|
+
*/
|
|
273
|
+
declare function normalize(parameters: MatchingParameters): MatchingParameters;
|
|
274
|
+
declare function mapAndSendFbqEvent<T extends EventName>(fbq: Fbq['fbq'], name: TrackName<T>, properties?: TrackProperties<T>, options?: {
|
|
275
|
+
eventID?: string;
|
|
276
|
+
}): void;
|
|
277
|
+
|
|
278
|
+
export { type Content, type Fbq, type MatchingParameters, type ObjectProperties, type PixelId, type StandardEvents, mapAndSendFbqEvent, normalize };
|
|
@@ -0,0 +1,278 @@
|
|
|
1
|
+
import { EventName, TrackName, TrackProperties } from './types.js';
|
|
2
|
+
import './gtag.js';
|
|
3
|
+
|
|
4
|
+
type Content = {
|
|
5
|
+
id: string;
|
|
6
|
+
quantity: number;
|
|
7
|
+
[key: string]: unknown;
|
|
8
|
+
};
|
|
9
|
+
/**
|
|
10
|
+
* reference: https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching
|
|
11
|
+
* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
|
|
12
|
+
*/
|
|
13
|
+
type MatchingParameters = {
|
|
14
|
+
/** Email: Unhashed lowercase or hashed SHA-256 */
|
|
15
|
+
em?: string;
|
|
16
|
+
/** First Name: Lowercase letters */
|
|
17
|
+
fn?: string;
|
|
18
|
+
/** Last Name: Lowercase letters */
|
|
19
|
+
ln?: string;
|
|
20
|
+
/** Phone Number: Digits only including country code and area code */
|
|
21
|
+
ph?: string;
|
|
22
|
+
/**
|
|
23
|
+
* External ID: Any unique ID from the advertiser, such as loyalty membership ID, user ID, and
|
|
24
|
+
* external cookie ID.
|
|
25
|
+
*/
|
|
26
|
+
external_id?: string;
|
|
27
|
+
/** Gender: Single lowercase letter, f or m, if unknown, leave blank */
|
|
28
|
+
ge?: 'f' | 'm' | '';
|
|
29
|
+
/** Birthdate: Digits only with birth year, month, then day, YYYYMMDD */
|
|
30
|
+
db?: number;
|
|
31
|
+
/** City: Lowercase with any spaces removed, e.g. "menlopark" */
|
|
32
|
+
ct?: string;
|
|
33
|
+
/** State or Province: Lowercase two-letter state or province code, e.g. "ca" */
|
|
34
|
+
st?: string;
|
|
35
|
+
/** Zip or Postal Code: String */
|
|
36
|
+
zp?: string;
|
|
37
|
+
/** Country: Lowercase two-letter country code, e.g. "us" */
|
|
38
|
+
country?: string;
|
|
39
|
+
/** Client IP Address: Do not hash. */
|
|
40
|
+
client_ip_address?: string;
|
|
41
|
+
/** Client User Agent: Do not hash. */
|
|
42
|
+
client_user_agent?: string;
|
|
43
|
+
/**
|
|
44
|
+
* Click ID: Do not hash.
|
|
45
|
+
* The Facebook click ID value is stored in the _fbc browser cookie under your domain. See
|
|
46
|
+
* Managing fbc and fbp Parameters for how to get this value or generate this value from a fbclid
|
|
47
|
+
* query parameter.
|
|
48
|
+
*
|
|
49
|
+
* The format is fb.${subdomain_index}.${creation_time}.${fbclid}.
|
|
50
|
+
*/
|
|
51
|
+
fbc?: string;
|
|
52
|
+
/**
|
|
53
|
+
* Browser ID: Do not hash.
|
|
54
|
+
* The Facebook browser ID value is stored in the _fbp browser cookie under your domain. See
|
|
55
|
+
* Managing fbc and fbp Parameters for how to get this value.
|
|
56
|
+
*
|
|
57
|
+
* The format is fb.${subdomain_index}.${creation_time}.${random_number}.
|
|
58
|
+
*/
|
|
59
|
+
fbp?: string;
|
|
60
|
+
/**
|
|
61
|
+
* Subscription ID: Do not hash.
|
|
62
|
+
* The subscription ID for the user in this transaction; it is similar to the order ID for an
|
|
63
|
+
* individual product.
|
|
64
|
+
*/
|
|
65
|
+
subscription_id?: string;
|
|
66
|
+
/**
|
|
67
|
+
* Facebook Login ID: Do not hash.
|
|
68
|
+
* The ID issued by Meta when a person first logs into an instance of an app. This is also known
|
|
69
|
+
* as App-Scoped ID.
|
|
70
|
+
*/
|
|
71
|
+
fb_login_id?: number;
|
|
72
|
+
/**
|
|
73
|
+
* Lead ID: Do not hash.
|
|
74
|
+
* The ID associated with a lead generated by [Meta's Lead Ads](https://developers.facebook.com/docs/marketing-api/guides/lead-ads).
|
|
75
|
+
*/
|
|
76
|
+
lead_id?: number;
|
|
77
|
+
/**
|
|
78
|
+
* Install ID: Do not hash.
|
|
79
|
+
* Your install ID. This field represents unique application installation instances.
|
|
80
|
+
* Note: This parameter is for app events only.
|
|
81
|
+
*/
|
|
82
|
+
anon_id?: string;
|
|
83
|
+
/**
|
|
84
|
+
* Your mobile advertiser ID, the advertising ID from an Android device or the Advertising
|
|
85
|
+
* Identifier (IDFA) from an Apple device.
|
|
86
|
+
*/
|
|
87
|
+
madid?: string;
|
|
88
|
+
/**
|
|
89
|
+
* Page ID: Do not hash.
|
|
90
|
+
* Your Page ID. Specifies the page ID associated with the event. Use the Facebook page ID of the
|
|
91
|
+
* page associated with the bot.
|
|
92
|
+
*/
|
|
93
|
+
page_id?: string;
|
|
94
|
+
/**
|
|
95
|
+
* Page Scoped User ID: Do not hash.
|
|
96
|
+
* Specifies the page-scoped user ID associated with the messenger bot that logs the event. Use
|
|
97
|
+
* the page-scoped user ID provided to your webhook.
|
|
98
|
+
*/
|
|
99
|
+
page_scoped_user_id?: string;
|
|
100
|
+
/**
|
|
101
|
+
* Do not hash.
|
|
102
|
+
* Click ID generated by Meta for ads that click to WhatsApp.
|
|
103
|
+
*/
|
|
104
|
+
ctwa_clid?: string;
|
|
105
|
+
/**
|
|
106
|
+
* Do not hash.
|
|
107
|
+
* Instagram Account ID that is associated with the business.
|
|
108
|
+
*/
|
|
109
|
+
ig_account_id?: string;
|
|
110
|
+
/**
|
|
111
|
+
* Do not hash.
|
|
112
|
+
* Users who interact with Instagram are identified by Instagram-Scoped User IDs (IGSID). IGSID
|
|
113
|
+
* can be obtained from this webhook.
|
|
114
|
+
*/
|
|
115
|
+
ig_sid?: string;
|
|
116
|
+
};
|
|
117
|
+
/**
|
|
118
|
+
* You can include the following predefined object properties with any custom events, and any
|
|
119
|
+
* standard events that support them. Format your parameter object data using JSON. Learn more about
|
|
120
|
+
* event parameters with Blueprint.
|
|
121
|
+
*/
|
|
122
|
+
type ObjectProperties = {
|
|
123
|
+
content_category?: string;
|
|
124
|
+
content_ids?: string[];
|
|
125
|
+
content_name?: string;
|
|
126
|
+
/**
|
|
127
|
+
* Either product or product_group based on the content_ids or contents being passed. If the IDs
|
|
128
|
+
* being passed in content_ids or contents parameter are IDs of products, then the value should be
|
|
129
|
+
* product. If product group IDs are being passed, then the value should be product_group.
|
|
130
|
+
*
|
|
131
|
+
* If no content_type is provided, Meta will match the event to every item that has the same ID,
|
|
132
|
+
* independent of its type.
|
|
133
|
+
*/
|
|
134
|
+
content_type?: 'product' | 'product_group' | (string & {});
|
|
135
|
+
contents?: Content[];
|
|
136
|
+
delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
|
|
137
|
+
currency?: string;
|
|
138
|
+
num_items?: number;
|
|
139
|
+
predicted_ltv?: number;
|
|
140
|
+
search_string?: string;
|
|
141
|
+
/** Used with the CompleteRegistration event, to show the status of the registration. */
|
|
142
|
+
status?: boolean;
|
|
143
|
+
value?: number;
|
|
144
|
+
};
|
|
145
|
+
/**
|
|
146
|
+
* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/payload-helper
|
|
147
|
+
*/
|
|
148
|
+
type StandardEvents = {
|
|
149
|
+
AddPaymentInfo: {
|
|
150
|
+
content_ids?: string[];
|
|
151
|
+
contents?: Content[];
|
|
152
|
+
currency?: string;
|
|
153
|
+
value?: number;
|
|
154
|
+
};
|
|
155
|
+
AddToCart: {
|
|
156
|
+
content_ids?: string[];
|
|
157
|
+
content_type?: string;
|
|
158
|
+
contents?: Content[];
|
|
159
|
+
currency?: string;
|
|
160
|
+
value?: number;
|
|
161
|
+
};
|
|
162
|
+
AddToWishlist: {
|
|
163
|
+
content_ids?: string[];
|
|
164
|
+
contents?: Content[];
|
|
165
|
+
currency?: string;
|
|
166
|
+
value?: number;
|
|
167
|
+
};
|
|
168
|
+
CompleteRegistration: {
|
|
169
|
+
currency?: string;
|
|
170
|
+
value?: number;
|
|
171
|
+
method?: string;
|
|
172
|
+
};
|
|
173
|
+
Contact: {};
|
|
174
|
+
CustomizeProduct: {};
|
|
175
|
+
Donate: {};
|
|
176
|
+
FindLocation: {};
|
|
177
|
+
InitiateCheckout: {
|
|
178
|
+
content_ids?: string[];
|
|
179
|
+
contents?: Content[];
|
|
180
|
+
currency?: string;
|
|
181
|
+
num_items?: number;
|
|
182
|
+
value?: number;
|
|
183
|
+
};
|
|
184
|
+
Lead: {
|
|
185
|
+
currency?: string;
|
|
186
|
+
value?: number;
|
|
187
|
+
};
|
|
188
|
+
Purchase: {
|
|
189
|
+
content_ids?: string[];
|
|
190
|
+
content_type?: string;
|
|
191
|
+
contents?: Content[];
|
|
192
|
+
currency: string;
|
|
193
|
+
num_items?: number;
|
|
194
|
+
value: number;
|
|
195
|
+
};
|
|
196
|
+
Schedule: {};
|
|
197
|
+
Search: {
|
|
198
|
+
content_ids?: string[];
|
|
199
|
+
content_type?: string;
|
|
200
|
+
contents?: Content[];
|
|
201
|
+
currency?: string;
|
|
202
|
+
search_string?: string;
|
|
203
|
+
value?: number;
|
|
204
|
+
};
|
|
205
|
+
StartTrial: {
|
|
206
|
+
currency?: string;
|
|
207
|
+
predicted_ltv?: number;
|
|
208
|
+
value?: number;
|
|
209
|
+
};
|
|
210
|
+
SubmitApplication: {};
|
|
211
|
+
Subscribe: {
|
|
212
|
+
currency?: string;
|
|
213
|
+
predicted_ltv?: number;
|
|
214
|
+
value?: number;
|
|
215
|
+
};
|
|
216
|
+
ViewContent: {
|
|
217
|
+
content_ids?: string[];
|
|
218
|
+
content_type?: string;
|
|
219
|
+
contents?: Content[];
|
|
220
|
+
currency?: string;
|
|
221
|
+
value?: number;
|
|
222
|
+
};
|
|
223
|
+
};
|
|
224
|
+
type JSONValue = null | string | number | boolean | Array<JSONValue> | {
|
|
225
|
+
[value: string]: JSONValue;
|
|
226
|
+
};
|
|
227
|
+
type PixelId = `${number}`;
|
|
228
|
+
/**
|
|
229
|
+
* reference: https://developers.facebook.com/docs/meta-pixel/reference#standard-events
|
|
230
|
+
*
|
|
231
|
+
* We determine if events are identical based on their ID and name. So, for an event to be deduplicated:
|
|
232
|
+
* - In corresponding events, a Meta Pixel's eventID must match the Conversion API's event_id.
|
|
233
|
+
* - In corresponding events, a Meta Pixel's event must match the Conversion API's event_name.
|
|
234
|
+
*
|
|
235
|
+
* reference: https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters
|
|
236
|
+
*/
|
|
237
|
+
interface Fbq {
|
|
238
|
+
/**
|
|
239
|
+
* reference: https://stackoverflow.com/questions/62304291/sending-user-data-parameters-via-pixel
|
|
240
|
+
*
|
|
241
|
+
* Call init the normal default way first:
|
|
242
|
+
* `fbq('init', 'XXXXX')`
|
|
243
|
+
*
|
|
244
|
+
* And at a later point in time, when you have obtained additional user data, you can call init
|
|
245
|
+
* again basically enriching the already running fbq instance with additional data:
|
|
246
|
+
* `fbq('init', 'XXXXX', { external_id: 1234, em: 'abc@abc.com' } )`
|
|
247
|
+
*
|
|
248
|
+
* Only caveat is that you have to send an event after this additional init call, otherwise the
|
|
249
|
+
* provided data will not be sent to Facebook.
|
|
250
|
+
*/
|
|
251
|
+
fbq(type: 'init', pixelId: PixelId, parameters?: MatchingParameters): void;
|
|
252
|
+
/** Enable Manual Only mode. (value = false) */
|
|
253
|
+
fbq(type: 'set', key: 'autoConfig', value: boolean, pixelId: PixelId): void;
|
|
254
|
+
fbq<T extends keyof StandardEvents>(type: 'track', event: T, properties?: StandardEvents[T] & ObjectProperties, options?: {
|
|
255
|
+
eventID?: string;
|
|
256
|
+
}): void;
|
|
257
|
+
fbq(type: 'trackCustom', event: string, properties?: Record<string, JSONValue> & ObjectProperties, options?: {
|
|
258
|
+
eventID?: string;
|
|
259
|
+
}): void;
|
|
260
|
+
/** https://developers.facebook.com/docs/meta-pixel/guides/track-multiple-events/ */
|
|
261
|
+
fbq<T extends keyof StandardEvents>(type: 'trackSingle', pixelId: PixelId, event: T, properties?: StandardEvents[T] & ObjectProperties, options?: {
|
|
262
|
+
eventID?: string;
|
|
263
|
+
}): void;
|
|
264
|
+
/** https://developers.facebook.com/docs/meta-pixel/guides/track-multiple-events/ */
|
|
265
|
+
fbq(type: 'trackSingleCustom', pixelId: PixelId, event: string, properties?: Record<string, JSONValue> & ObjectProperties, options?: {
|
|
266
|
+
eventID?: string;
|
|
267
|
+
}): void;
|
|
268
|
+
}
|
|
269
|
+
/**
|
|
270
|
+
* Please download this CSV filefor examples of properly normalized and hashed data for the
|
|
271
|
+
* parameters below.
|
|
272
|
+
*/
|
|
273
|
+
declare function normalize(parameters: MatchingParameters): MatchingParameters;
|
|
274
|
+
declare function mapAndSendFbqEvent<T extends EventName>(fbq: Fbq['fbq'], name: TrackName<T>, properties?: TrackProperties<T>, options?: {
|
|
275
|
+
eventID?: string;
|
|
276
|
+
}): void;
|
|
277
|
+
|
|
278
|
+
export { type Content, type Fbq, type MatchingParameters, type ObjectProperties, type PixelId, type StandardEvents, mapAndSendFbqEvent, normalize };
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
// src/track/fbq.ts
|
|
2
|
+
function normalize(parameters) {
|
|
3
|
+
var _a, _b, _c, _d, _e, _f, _g, _h, _i;
|
|
4
|
+
return {
|
|
5
|
+
...parameters,
|
|
6
|
+
em: (_a = parameters.em) == null ? void 0 : _a.toLowerCase().trim(),
|
|
7
|
+
ph: (_b = parameters.ph) == null ? void 0 : _b.replace(/[\+\-\(\)\s]/g, "").replace(/^0+/, ""),
|
|
8
|
+
zp: (_d = (_c = parameters.zp) == null ? void 0 : _c.split("-").at(0)) == null ? void 0 : _d.trim(),
|
|
9
|
+
fn: (_e = parameters.fn) == null ? void 0 : _e.toLowerCase().trim(),
|
|
10
|
+
ln: (_f = parameters.ln) == null ? void 0 : _f.toLowerCase().trim(),
|
|
11
|
+
ct: (_g = parameters.ct) == null ? void 0 : _g.toLowerCase().replace(/[s/-]/g, "").trim(),
|
|
12
|
+
st: (_h = parameters.st) == null ? void 0 : _h.toLowerCase().replace(/[s/-/,.]/g, "").trim(),
|
|
13
|
+
country: (_i = parameters.country) == null ? void 0 : _i.toLowerCase().replace(/[s/-]/g, "").trim()
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
function mapItems(items) {
|
|
17
|
+
if (!items) return {};
|
|
18
|
+
const categories = Array.from(new Set(items.map((i) => i.item_category).filter(Boolean)));
|
|
19
|
+
const contents = items.map(({ item_id, quantity, ...others }) => ({
|
|
20
|
+
id: item_id,
|
|
21
|
+
quantity: quantity ?? 1,
|
|
22
|
+
...Object.fromEntries(
|
|
23
|
+
Object.entries(others).map(([key, value]) => [key.replace("item_", ""), value])
|
|
24
|
+
)
|
|
25
|
+
}));
|
|
26
|
+
return {
|
|
27
|
+
content_category: categories.length === 1 ? categories.at(0) : void 0,
|
|
28
|
+
contents,
|
|
29
|
+
content_ids: contents.map((c) => c.id),
|
|
30
|
+
num_items: items.reduce((acc, i) => acc + (i.quantity ?? 1), 0)
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
function mapAndSendFbqEvent(fbq, name, properties, options) {
|
|
34
|
+
if (name === "add_payment_info") {
|
|
35
|
+
const p = properties;
|
|
36
|
+
fbq(
|
|
37
|
+
"track",
|
|
38
|
+
"AddPaymentInfo",
|
|
39
|
+
{ currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) },
|
|
40
|
+
options
|
|
41
|
+
);
|
|
42
|
+
} else if (name === "add_to_cart") {
|
|
43
|
+
const p = properties;
|
|
44
|
+
fbq(
|
|
45
|
+
"track",
|
|
46
|
+
"AddToCart",
|
|
47
|
+
{ currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) },
|
|
48
|
+
options
|
|
49
|
+
);
|
|
50
|
+
} else if (name === "add_to_wishlist") {
|
|
51
|
+
const p = properties;
|
|
52
|
+
fbq(
|
|
53
|
+
"track",
|
|
54
|
+
"AddToWishlist",
|
|
55
|
+
{ currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) },
|
|
56
|
+
options
|
|
57
|
+
);
|
|
58
|
+
} else if (name === "login") {
|
|
59
|
+
const p = properties;
|
|
60
|
+
fbq("track", "CompleteRegistration", { method: p == null ? void 0 : p.method }, options);
|
|
61
|
+
} else if (name === "contact") {
|
|
62
|
+
fbq("track", "Contact", {}, options);
|
|
63
|
+
} else if (name === "customize_product") {
|
|
64
|
+
fbq("track", "CustomizeProduct", {}, options);
|
|
65
|
+
} else if (name === "donate") {
|
|
66
|
+
fbq("track", "Donate", {}, options);
|
|
67
|
+
} else if (name === "find_location") {
|
|
68
|
+
fbq("track", "FindLocation", {}, options);
|
|
69
|
+
} else if (name === "begin_checkout") {
|
|
70
|
+
const p = properties;
|
|
71
|
+
fbq(
|
|
72
|
+
"track",
|
|
73
|
+
"InitiateCheckout",
|
|
74
|
+
{ currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) },
|
|
75
|
+
options
|
|
76
|
+
);
|
|
77
|
+
} else if (name === "generate_lead") {
|
|
78
|
+
const p = properties;
|
|
79
|
+
fbq("track", "Lead", { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value }, options);
|
|
80
|
+
} else if (name === "purchase") {
|
|
81
|
+
const p = properties;
|
|
82
|
+
fbq(
|
|
83
|
+
"track",
|
|
84
|
+
"Purchase",
|
|
85
|
+
p ? { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) } : void 0,
|
|
86
|
+
options
|
|
87
|
+
);
|
|
88
|
+
} else if (name === "schedule") {
|
|
89
|
+
fbq("track", "Schedule", {}, options);
|
|
90
|
+
} else if (name === "search") {
|
|
91
|
+
const p = properties;
|
|
92
|
+
fbq("track", "Search", { search_string: p == null ? void 0 : p.search_term }, options);
|
|
93
|
+
} else if (name === "trial_begin") {
|
|
94
|
+
const p = properties;
|
|
95
|
+
fbq("track", "StartTrial", { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value }, options);
|
|
96
|
+
} else if (name === "submit_application") {
|
|
97
|
+
fbq("track", "SubmitApplication", {}, options);
|
|
98
|
+
} else if (name === "subscribe") {
|
|
99
|
+
const p = properties;
|
|
100
|
+
fbq("track", "Subscribe", { currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value }, options);
|
|
101
|
+
} else if (name === "view_item") {
|
|
102
|
+
const p = properties;
|
|
103
|
+
fbq(
|
|
104
|
+
"track",
|
|
105
|
+
"ViewContent",
|
|
106
|
+
{ currency: p == null ? void 0 : p.currency, value: p == null ? void 0 : p.value, ...mapItems(p == null ? void 0 : p.items) },
|
|
107
|
+
options
|
|
108
|
+
);
|
|
109
|
+
} else {
|
|
110
|
+
fbq("trackCustom", name, properties, options);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
export {
|
|
114
|
+
mapAndSendFbqEvent,
|
|
115
|
+
normalize
|
|
116
|
+
};
|
|
117
|
+
//# sourceMappingURL=fbq.mjs.map
|