@lemuai/analytics 0.0.0-stage → 1.0.0
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/LICENSE +21 -0
- package/README.md +172 -2
- package/core/package.json +7 -0
- package/dist/chunk-6XUDD2XU.js +656 -0
- package/dist/chunk-6XUDD2XU.js.map +1 -0
- package/dist/core.cjs +667 -0
- package/dist/core.cjs.map +1 -0
- package/dist/core.d.cts +328 -0
- package/dist/core.d.ts +328 -0
- package/dist/core.js +3 -0
- package/dist/core.js.map +1 -0
- package/dist/index.cjs +838 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +50 -0
- package/dist/index.d.ts +50 -0
- package/dist/index.js +170 -0
- package/dist/index.js.map +1 -0
- package/dist/lemu.js +1 -0
- package/package.json +45 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 LemuAI
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,173 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @lemuai/analytics
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Lemu tracking for websites: page views, events, purchases and known users, sent to your Lemu workspace so journeys, segments and ROI reports can use them.
|
|
4
|
+
|
|
5
|
+
- Zero runtime dependencies, about 5.5 KB gzipped as a script tag.
|
|
6
|
+
- Works with or without a bundler. Safe to import during server-side rendering.
|
|
7
|
+
- Standard events use Meta's names, so the same event names work for the Meta pixel and for Lemu.
|
|
8
|
+
|
|
9
|
+
For React and Next.js use [`@lemuai/react`](../react). For React Native and Expo use [`@lemuai/react-native`](../react-native).
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
With a bundler:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install @lemuai/analytics
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Or paste the snippet into your site's `<head>`. It loads the script from Lemu and queues calls until it arrives:
|
|
20
|
+
|
|
21
|
+
```html
|
|
22
|
+
<script>
|
|
23
|
+
!function(w,d){w.lemu=w.lemu||function(){(w.lemu.q=w.lemu.q||[]).push(arguments)};
|
|
24
|
+
var s=d.createElement("script");s.async=1;s.src="https://app.lemuai.com/api/v1/pixel/sdk.js";
|
|
25
|
+
d.head.appendChild(s)}(window,document);
|
|
26
|
+
lemu("init", "YOUR_WRITE_KEY");
|
|
27
|
+
lemu("page");
|
|
28
|
+
</script>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
The same file is published as `@lemuai/analytics/dist/lemu.js` if you prefer to load it from a CDN or host it yourself. Loaded from `/api/v1/pixel/sdk.js`, it sends events back to that host; loaded from anywhere else, it sends to `https://app.lemuai.com` unless you pass `apiHost`.
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
import { lemu, LemuEvent } from "@lemuai/analytics";
|
|
37
|
+
|
|
38
|
+
lemu.init("YOUR_WRITE_KEY");
|
|
39
|
+
lemu.page();
|
|
40
|
+
|
|
41
|
+
lemu.track(LemuEvent.AddToCart, {
|
|
42
|
+
value: 999,
|
|
43
|
+
currency: "INR",
|
|
44
|
+
content_ids: ["SKU1"],
|
|
45
|
+
content_type: "product",
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
With the snippet, every method is called by name: `lemu("track", "AddToCart", { value: 999, currency: "INR" })`.
|
|
50
|
+
|
|
51
|
+
## Standard events
|
|
52
|
+
|
|
53
|
+
Use these names (available as `LemuEvent.*` constants) so Lemu's reports, journeys and ad integrations recognise them. They are [Meta's standard events](https://developers.facebook.com/docs/meta-pixel/reference) with the same parameters. Any other name works too, as a custom event.
|
|
54
|
+
|
|
55
|
+
| Constant | Event name | Common properties |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `LemuEvent.PageView` | `PageView` | (none; `page()` covers this) |
|
|
58
|
+
| `LemuEvent.ViewContent` | `ViewContent` | `content_ids`, `content_name`, `content_type`, `value`, `currency` |
|
|
59
|
+
| `LemuEvent.Search` | `Search` | `search_string`, `content_ids` |
|
|
60
|
+
| `LemuEvent.AddToCart` | `AddToCart` | `content_ids`, `contents`, `value`, `currency` |
|
|
61
|
+
| `LemuEvent.AddToWishlist` | `AddToWishlist` | `content_ids`, `value`, `currency` |
|
|
62
|
+
| `LemuEvent.InitiateCheckout` | `InitiateCheckout` | `contents`, `num_items`, `value`, `currency` |
|
|
63
|
+
| `LemuEvent.AddPaymentInfo` | `AddPaymentInfo` | `value`, `currency` |
|
|
64
|
+
| `LemuEvent.Purchase` | `Purchase` | `value`, `currency`, `order_id` (required); use `purchase()` |
|
|
65
|
+
| `LemuEvent.Lead` | `Lead` | `content_name`, `value`, `currency` |
|
|
66
|
+
| `LemuEvent.CompleteRegistration` | `CompleteRegistration` | `status`, `value`, `currency` |
|
|
67
|
+
| `LemuEvent.Subscribe` | `Subscribe` | `value`, `currency`, `predicted_ltv` |
|
|
68
|
+
| `LemuEvent.StartTrial` | `StartTrial` | `value`, `currency`, `predicted_ltv` |
|
|
69
|
+
| `LemuEvent.Schedule` | `Schedule` | |
|
|
70
|
+
| `LemuEvent.SubmitApplication` | `SubmitApplication` | |
|
|
71
|
+
| `LemuEvent.Contact` | `Contact` | |
|
|
72
|
+
| `LemuEvent.CustomizeProduct` | `CustomizeProduct` | |
|
|
73
|
+
| `LemuEvent.Donate` | `Donate` | |
|
|
74
|
+
| `LemuEvent.FindLocation` | `FindLocation` | |
|
|
75
|
+
|
|
76
|
+
`value` is in major units (1499.5 means Rs 1,499.50) and `currency` is an ISO 4217 code such as `INR`. `contents` is a list of `{ id, quantity, item_price }`.
|
|
77
|
+
|
|
78
|
+
## Purchases
|
|
79
|
+
|
|
80
|
+
```js
|
|
81
|
+
lemu.purchase({
|
|
82
|
+
value: 1499.5,
|
|
83
|
+
currency: "INR",
|
|
84
|
+
order_id: "1042",
|
|
85
|
+
contents: [{ id: "SKU1", quantity: 1, item_price: 1499.5 }],
|
|
86
|
+
});
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
`purchase()` sends a `Purchase` event and sends it at once, without waiting for the next batch, so it isn't lost if the visitor closes the tab on the thank-you page.
|
|
90
|
+
|
|
91
|
+
`value`, `currency` and `order_id` are required. `order_id` matters most: the same order is often reported by more than one source (this page, your Shopify or payment webhook, a reload of the thank-you page). Lemu counts one conversion per `order_id`, so revenue isn't double counted and journeys get the right credit. Lemu never rejects an event for a missing field, but it flags the conversion as incomplete.
|
|
92
|
+
|
|
93
|
+
## Identify
|
|
94
|
+
|
|
95
|
+
Call `identify` when the visitor signs up or logs in. Pass your own user id and their contact details as traits:
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
lemu.identify("crm-123", {
|
|
99
|
+
email: "asha@example.com",
|
|
100
|
+
phone: "+919876543210",
|
|
101
|
+
first_name: "Asha",
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The user id is kept and sent on every later event until `reset()`. `identify(traits)` without an id works too. Traits are the only place for contact details: Lemu removes keys such as `email` and `phone` from event properties.
|
|
106
|
+
|
|
107
|
+
On logout, call `reset()`. The visitor gets a new anonymous id and the user id is cleared.
|
|
108
|
+
|
|
109
|
+
## Consent and opt-out
|
|
110
|
+
|
|
111
|
+
If you need consent before tracking, start with `requireConsent`:
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
lemu.init("YOUR_WRITE_KEY", { requireConsent: true });
|
|
115
|
+
|
|
116
|
+
// later, from your consent banner
|
|
117
|
+
lemu.setConsent(true); // snippet: lemu("consent", true)
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Until consent, nothing is sent and nothing is written to cookies or localStorage, not even the visitor id. Up to 50 events are held in memory and sent once consent is given. `setConsent(false)` discards them. A granted consent is remembered in localStorage (`_lemu_consent`), so returning visitors aren't asked again; `setConsent(false)` forgets it.
|
|
121
|
+
|
|
122
|
+
`lemu.optOut()` stops all tracking and clears the queue. It is remembered in a cookie and localStorage. `lemu.optIn()` undoes it.
|
|
123
|
+
|
|
124
|
+
## Single-page apps
|
|
125
|
+
|
|
126
|
+
`lemu.init(key, { trackPageChanges: true })` sends `page()` on `history.pushState` and back/forward navigation. In React, use `usePageTracking` from `@lemuai/react` instead.
|
|
127
|
+
|
|
128
|
+
## Debug mode
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
lemu.init("YOUR_WRITE_KEY", { debug: true });
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Logs every call, request and response to the console with a `[lemu]` prefix. Bad arguments (an empty event name, properties that can't be turned into JSON) are logged in debug mode and otherwise ignored. The SDK never throws into your code.
|
|
135
|
+
|
|
136
|
+
## Options
|
|
137
|
+
|
|
138
|
+
| Option | Default | |
|
|
139
|
+
|---|---|---|
|
|
140
|
+
| `apiHost` | `https://app.lemuai.com` | Collection host. The snippet uses the host it was loaded from |
|
|
141
|
+
| `debug` | `false` | Log calls, requests and responses |
|
|
142
|
+
| `requireConsent` | `false` | Hold events until `setConsent(true)` |
|
|
143
|
+
| `flushAt` | `10` | Send when this many events are queued |
|
|
144
|
+
| `flushInterval` | `1000` | Send queued events after this many milliseconds |
|
|
145
|
+
| `maxQueueSize` | `1000` | Most events kept while offline |
|
|
146
|
+
| `cookieDomain` | (current host) | Share the visitor id across subdomains, for example `.example.com` |
|
|
147
|
+
| `trackPageChanges` | `false` | `page()` on single-page-app navigation |
|
|
148
|
+
|
|
149
|
+
## API
|
|
150
|
+
|
|
151
|
+
| Method | |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `init(writeKey, options?)` | Start. Calls made before `init` are kept and run after it |
|
|
154
|
+
| `page(name?, properties?)` | A page view, with url, path, title and referrer |
|
|
155
|
+
| `track(event, properties?)` | Any event |
|
|
156
|
+
| `purchase({ value, currency, order_id, ... })` | A `Purchase`, sent at once |
|
|
157
|
+
| `identify(userId?, traits?)` | Set the user id and send traits |
|
|
158
|
+
| `reset()` | New anonymous id, user id cleared |
|
|
159
|
+
| `flush()` | Send now. Returns a promise |
|
|
160
|
+
| `setConsent(granted)` | Start or stop sending under `requireConsent` |
|
|
161
|
+
| `optOut()` / `optIn()` | Stop or resume all tracking, remembered |
|
|
162
|
+
| `anonymousId()` | The visitor id, or `null` before consent or after opt-out |
|
|
163
|
+
| `createLemu()` | A separate client, for more than one source on a page |
|
|
164
|
+
|
|
165
|
+
Events are batched and sent as `text/plain` (no CORS preflight), every second or every 10 events, and with `sendBeacon` when the page is hidden. Failed requests are retried with backoff. The visitor id lives in the `_lemu_aid` first-party cookie and localStorage, the same as earlier versions of the snippet, so returning visitors keep their id.
|
|
166
|
+
|
|
167
|
+
## Other platforms
|
|
168
|
+
|
|
169
|
+
`@lemuai/analytics/core` is the platform-agnostic client with pluggable storage, transport, context and lifecycle adapters. `@lemuai/react-native` is built on it. The wire protocol is documented in [`spec/protocol.md`](../../../spec/protocol.md).
|
|
170
|
+
|
|
171
|
+
## License
|
|
172
|
+
|
|
173
|
+
MIT
|