Merge 66482b2 into 90e1daa

README.md

@@ -105,6 +105,45 @@ We can also fire an event on any other type of user interaction and give it a cu
 pagesAnalytics.track({eventType: 'C_MY_CUSTOM_EVENT'});
 ```
 
+### Conversion Tracking
+
+Yext offers conversion tracking that can attribute values to conversion events that are driven by user interaction
+with Yext's products.  Once you have [setup conversion tracking](https://hitchhikers.yext.com/modules/ana104-conversion/01-conversion-overview/)
+you can create a conversionTracking provider like so:
+
+```ts
+import { provideConversionTrackingAnalytics } from '@yext/analytics';
+const conversionTracker = provideConversionTrackingAnalytics();
+```
+
+In order to track conversions, you will need to set a Cookie on your users and pass the id of that cookie to the 
+conversion tracker when a conversion event occurs.  Which can be done like so:
+
+```ts
+conversionTracker.trackConversion({
+  cookieId: '12466678', //the unique id that you generated for the user cookie
+  cid: '12345-abcde-67890-fghij', //the value of the tag found in the conversion tracking setup page in your account
+  cv: 10, // the optional monetary value of the conversion event.
+})
+```
+
+Additionally, if you are implementing Conversion tracking on a pages site, once you have setup the pages analytics
+tracker, you should turn on conversion tracking so that interactions on your pages site can be properly credited with 
+conversions.  That can be done like so:
+
+```ts
+pagesAnalytics.setConversionTrackingEnabled(true, 'cookie id of the user goes here');
+```
+
+Then, when you track a page view it will automatically be credited for conversion tracking purposes. Additionally, if
+an event on your pages should be treated as a conversion, you would track it like so:
+
+```ts
+pagesAnalytics.track('event_to_track', {
+  cid: '12345-abcde-67890-fghij', // the value of the tag found in the conversion tracking setup page in your account
+  cv: 10, // the optional monetary value of the conversion event.
+});
+```
 
 And that's it! See **[our documentation](./docs/analytics.md)** for a full list of analytics events.
 

docs/analytics.commonconversiondata.cookieid.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CommonConversionData](./analytics.commonconversiondata.md) &gt; [cookieId](./analytics.commonconversiondata.cookieid.md)
+
+## CommonConversionData.cookieId property
+
+A cookie id from a first party cookie (i.e. from a visit to a domain you control)
+
+<b>Signature:</b>
+
+```typescript
+cookieId: string;
+```

docs/analytics.commonconversiondata.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CommonConversionData](./analytics.commonconversiondata.md)
+
+## CommonConversionData interface
+
+Shared properties of both ConversionEvent and ListingsClickEvent
+
+<b>Signature:</b>
+
+```typescript
+export interface CommonConversionData 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [cookieId](./analytics.commonconversiondata.cookieid.md) | string | A cookie id from a first party cookie (i.e. from a visit to a domain you control) |
+|  [referrer?](./analytics.commonconversiondata.referrer.md) | string | <i>(Optional)</i> Page which sent the user to the current page, comes from typically Document.referrer |
+

docs/analytics.commonconversiondata.referrer.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CommonConversionData](./analytics.commonconversiondata.md) &gt; [referrer](./analytics.commonconversiondata.referrer.md)
+
+## CommonConversionData.referrer property
+
+Page which sent the user to the current page, comes from typically Document.referrer
+
+<b>Signature:</b>
+
+```typescript
+referrer?: string;
+```

docs/analytics.conversiondetails.cid.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionDetails](./analytics.conversiondetails.md) &gt; [cid](./analytics.conversiondetails.cid.md)
+
+## ConversionDetails.cid property
+
+The id of the conversion tag, you can find the value from the conversion tracking section in your Yext account. You can find a list of tags under: https://www.yext.com/s/\[your business id\]/reports/conversiontracking/setup
+
+<b>Signature:</b>
+
+```typescript
+cid: string;
+```

docs/analytics.conversiondetails.cv.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionDetails](./analytics.conversiondetails.md) &gt; [cv](./analytics.conversiondetails.cv.md)
+
+## ConversionDetails.cv property
+
+Conversion Value Optional custom value supplied for this conversion
+
+<b>Signature:</b>
+
+```typescript
+cv?: string;
+```

docs/analytics.conversiondetails.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionDetails](./analytics.conversiondetails.md)
+
+## ConversionDetails interface
+
+The details of an individual conversion event, without the cookie id.
+
+<b>Signature:</b>
+
+```typescript
+export interface ConversionDetails 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [cid](./analytics.conversiondetails.cid.md) | string | The id of the conversion tag, you can find the value from the conversion tracking section in your Yext account. You can find a list of tags under: https://www.yext.com/s/\[your business id\]/reports/conversiontracking/setup |
+|  [cv?](./analytics.conversiondetails.cv.md) | string | <i>(Optional)</i> Conversion Value Optional custom value supplied for this conversion |
+

docs/analytics.conversionevent.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionEvent](./analytics.conversionevent.md)
+
+## ConversionEvent interface
+
+An event representing a Conversion
+
+<b>Signature:</b>
+
+```typescript
+export interface ConversionEvent extends CommonConversionData, ConversionDetails 
+```
+<b>Extends:</b> [CommonConversionData](./analytics.commonconversiondata.md)<!-- -->, [ConversionDetails](./analytics.conversiondetails.md)
+

docs/analytics.conversiontrackingservice.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionTrackingService](./analytics.conversiontrackingservice.md)
+
+## ConversionTrackingService interface
+
+A service for tracking conversions
+
+<b>Signature:</b>
+
+```typescript
+export interface ConversionTrackingService 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [setDebugEnabled(enabled)](./analytics.conversiontrackingservice.setdebugenabled.md) | Turns on debug logging for event details. Will log details to the console when report() is called. |
+|  [trackConversion(event)](./analytics.conversiontrackingservice.trackconversion.md) | tracks a conversion event |
+|  [trackListings(event)](./analytics.conversiontrackingservice.tracklistings.md) | tracks a user's arrival on a landing page from a listings publisher |
+

docs/analytics.conversiontrackingservice.setdebugenabled.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionTrackingService](./analytics.conversiontrackingservice.md) &gt; [setDebugEnabled](./analytics.conversiontrackingservice.setdebugenabled.md)
+
+## ConversionTrackingService.setDebugEnabled() method
+
+Turns on debug logging for event details. Will log details to the console when report() is called.
+
+<b>Signature:</b>
+
+```typescript
+setDebugEnabled(enabled: boolean): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  enabled | boolean | whether debug logging should be turned on |
+
+<b>Returns:</b>
+
+void
+

docs/analytics.conversiontrackingservice.trackconversion.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionTrackingService](./analytics.conversiontrackingservice.md) &gt; [trackConversion](./analytics.conversiontrackingservice.trackconversion.md)
+
+## ConversionTrackingService.trackConversion() method
+
+tracks a conversion event
+
+<b>Signature:</b>
+
+```typescript
+trackConversion(event: ConversionEvent): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  event | [ConversionEvent](./analytics.conversionevent.md) | a Conversion event |
+
+<b>Returns:</b>
+
+void
+

docs/analytics.conversiontrackingservice.tracklistings.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ConversionTrackingService](./analytics.conversiontrackingservice.md) &gt; [trackListings](./analytics.conversiontrackingservice.tracklistings.md)
+
+## ConversionTrackingService.trackListings() method
+
+tracks a user's arrival on a landing page from a listings publisher
+
+<b>Signature:</b>
+
+```typescript
+trackListings(event: ListingsClickEvent): Promise<void>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  event | [ListingsClickEvent](./analytics.listingsclickevent.md) | the event to track |
+
+<b>Returns:</b>
+
+Promise&lt;void&gt;
+

docs/analytics.cookie_param.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [COOKIE\_PARAM](./analytics.cookie_param.md)
+
+## COOKIE\_PARAM variable
+
+URL Parameter &amp; Param name for Yext conversion pixels
+
+<b>Signature:</b>
+
+```typescript
+COOKIE_PARAM = "_yfpc"
+```

docs/analytics.cookiemanager._constructor_.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CookieManager](./analytics.cookiemanager.md) &gt; [(constructor)](./analytics.cookiemanager._constructor_.md)
+
+## CookieManager.(constructor)
+
+Takes the window and document
+
+<b>Signature:</b>
+
+```typescript
+constructor(_outerWindow?: Window, _outerDocument?: Document);
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  \_outerWindow | Window | typically the window object or a mock |
+|  \_outerDocument | Document | typically teh document object or a mock |
+

docs/analytics.cookiemanager.md

@@ -0,0 +1,26 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CookieManager](./analytics.cookiemanager.md)
+
+## CookieManager class
+
+CookieManager will manager conversion tracking cookies
+
+<b>Signature:</b>
+
+```typescript
+export declare class CookieManager 
+```
+
+## Constructors
+
+|  Constructor | Modifiers | Description |
+|  --- | --- | --- |
+|  [(constructor)(\_outerWindow, \_outerDocument)](./analytics.cookiemanager._constructor_.md) |  | Takes the window and document |
+
+## Methods
+
+|  Method | Modifiers | Description |
+|  --- | --- | --- |
+|  [setAndGetYextCookie()](./analytics.cookiemanager.setandgetyextcookie.md) |  | Gets the existing YFPC ID, or sets a new one if it doesn't already exist. You should only call this method if doing so complies with your GDPR/CCPA compliance requirements. |
+

docs/analytics.cookiemanager.setandgetyextcookie.md

@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [CookieManager](./analytics.cookiemanager.md) &gt; [setAndGetYextCookie](./analytics.cookiemanager.setandgetyextcookie.md)
+
+## CookieManager.setAndGetYextCookie() method
+
+Gets the existing YFPC ID, or sets a new one if it doesn't already exist. You should only call this method if doing so complies with your GDPR/CCPA compliance requirements.
+
+<b>Signature:</b>
+
+```typescript
+setAndGetYextCookie(): string;
+```
+<b>Returns:</b>
+
+string
+

docs/analytics.listingsclickevent.location.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ListingsClickEvent](./analytics.listingsclickevent.md) &gt; [location](./analytics.listingsclickevent.location.md)
+
+## ListingsClickEvent.location property
+
+The url of the landing page.
+
+<b>Signature:</b>
+
+```typescript
+location: string;
+```

docs/analytics.listingsclickevent.md

@@ -0,0 +1,22 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ListingsClickEvent](./analytics.listingsclickevent.md)
+
+## ListingsClickEvent interface
+
+An event representing a user arriving at a landing page from a publisher site.
+
+<b>Signature:</b>
+
+```typescript
+export interface ListingsClickEvent extends CommonConversionData 
+```
+<b>Extends:</b> [CommonConversionData](./analytics.commonconversiondata.md)
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [location](./analytics.listingsclickevent.location.md) | string | The url of the landing page. |
+|  [source](./analytics.listingsclickevent.source.md) | string | The source parameter signifying which listings publisher should get credit Comes from the y\_source URL Parameter. |
+

docs/analytics.listingsclickevent.source.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/analytics](./analytics.md) &gt; [ListingsClickEvent](./analytics.listingsclickevent.md) &gt; [source](./analytics.listingsclickevent.source.md)
+
+## ListingsClickEvent.source property
+
+The source parameter signifying which listings publisher should get credit Comes from the y\_source URL Parameter.
+
+<b>Signature:</b>
+
+```typescript
+source: string;
+```