feat(request): adds support for custom event properties

Adds support for custom event properties through the EventOption 'props' value.

fix #2

README.md

@@ -108,8 +108,6 @@ trackPageview({
 
 The second parameter is an object with [some options](https://plausible-tracker.netlify.app/globals.html#eventoptions) similar to the ones provided by the [official Plausible script](https://docs.plausible.io/custom-event-goals). 
 
-The only supported option at the moment is `callback` – a function that is called once the event is logged successfully.
-
 ```ts
 import Plausible from 'plausible-tracker'
 
@@ -177,6 +175,12 @@ const { trackEvent } = Plausible()
 trackEvent('signup')
 ```
 
+Custom props can be provided using the third parameter:
+```ts
+// Tracks the 'Download' goal and provides a 'method' property.
+trackEvent('signup', {}, { props: { method: 'HTTP' } })
+```
+
 As with [`trackPageview`](#tracking-page-views), you may also provide override values and a callback as the second and third parameters respectively:
 
 ```ts
@@ -186,11 +190,16 @@ const { trackEvent } = Plausible({
   trackLocalhost: false,
 })
 
-// Tracks the 'signup' goal with a different referrer and a callback
+// Tracks the 'signup' goal with a different referrer, a callback and props
 trackEvent(
   'signup',
   { trackLocalhost: true },
-  { callback: () => console.log('done') }
+  {
+    callback: () => console.log('done'),
+    props: {
+      variation: 'button A'
+    }
+  }
 );
 ```
 

src/lib/request.spec.ts

@@ -121,4 +121,21 @@ describe('sendEvent', () => {
     xhrMockClass.ready(4);
     expect(callback).toHaveBeenCalled();
   });
+  test('sends props', () => {
+    expect(xmr).not.toHaveBeenCalled();
+    const props = { variation1: 'A', variation2: 'B' };
+    sendEvent('myEvent', defaultData, { props });
+
+    const payload = {
+      n: 'myEvent',
+      u: defaultData.url,
+      d: defaultData.domain,
+      r: defaultData.referrer,
+      w: defaultData.deviceWidth,
+      h: 0,
+      p: JSON.stringify(props)
+    };
+
+    expect(xhrMockClass.send).toHaveBeenCalledWith(JSON.stringify(payload));
+  });
 });

src/lib/request.ts

@@ -10,10 +10,19 @@ type EventPayload = {
   readonly r: Document['referrer'] | null;
   readonly w: Window['innerWidth'];
   readonly h: 1 | 0;
+  readonly p?: string;
 };
 
+// eslint-disable-next-line functional/no-mixed-type
 export type EventOptions = {
+  /**
+   * Callback called when the event is successfully sent.
+   */
   readonly callback?: () => void;
+  /**
+   * Properties to be bound to the event.
+   */
+  readonly props?: { readonly [propName: string]: string }
 };
 
 /**
@@ -46,6 +55,7 @@ export function sendEvent(
     r: data.referrer,
     w: data.deviceWidth,
     h: data.hashMode ? 1 : 0,
+    p: options && options.props ? JSON.stringify(options.props) : undefined
   };
 
   const req = new XMLHttpRequest();

src/lib/tracker.spec.ts

@@ -32,6 +32,10 @@ describe('tracker', () => {
 
   const getEventOptions: () => Required<requestModule.EventOptions> = () => ({
     callback: jest.fn(),
+    props: {
+      variation1: 'A',
+      variation2: 'B'
+    }
   });
 
   test('inits with default config', () => {

src/lib/tracker.ts

@@ -64,11 +64,14 @@ export type PlausibleOptions = PlausibleInitOptions & PlausibleEventData;
  *
  * // Tracks the 'signup' goal
  * trackEvent('signup')
+ * 
+ * // Tracks the 'Download' goal passing a 'method' property.
+ * trackEvent('Download', {}, { props: { method: 'HTTP' } })
  * ```
  *
  * @param eventName - Name of the event to track
  * @param eventData - Optional event data to send. Defaults to the current page's data merged with the default options provided earlier.
- * @param options - Event options. The only supported option at the moment is `callback` – a function that is called once the event is logged successfully.
+ * @param options - Event options.
  */
 type TrackEvent = (
   eventName: string,
@@ -90,7 +93,7 @@ type TrackEvent = (
  * ```
  *
  * @param eventData - Optional event data to send. Defaults to the current page's data merged with the default options provided earlier.
- * @param options - Event options. The only supported option at the moment is `callback` – a function that is called once the event is logged successfully.
+ * @param options - Event options.
  */
 type TrackPageview = (
   eventData?: PlausibleOptions,