Merge pull request #26 from PiwikPRO/feature/new-ecommerce-methods-v2

Feature/new ecommerce methods v2
PiwikPRO · Jan 25, 2024 · 29a2b09 · 29a2b09
2 parents b113367 + 6c8cb06
commit 29a2b09
Show file tree

Hide file tree

Showing 33 changed files with 3,591 additions and 2,744 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -7,7 +7,7 @@
     "standard",
     "standard-react",
     "plugin:prettier/recommended",
-    "prettier/standard",
+    "prettier",
     "prettier/react",
     "plugin:@typescript-eslint/eslint-recommended"
   ],

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,21 @@
 # CHANGELOG
 
+* [2.1.1](#2.1.1)
+* [2.1.0](#2.1.0)
 * [2.0.0](#2.0.0)
 * [1.0.1](#1.0.1)
 * [1.0.0](#1.0.0)
 
+## 2.1.1
+
+- Use new react-piwik-pro package version (1.3.3) with support of deprecated ecommerce methods.
+
+## 2.1.0
+
+- Use new react-piwik-pro package version (1.3.1) with new ecommerce methods.
+- Add new ecommerce methods to the example.
+- next now as peerDependencies.
+
 ## 2.0.0
 
 Support for Next > 13.0.0. New examples how to use added.

diff --git a/README.md b/README.md
@@ -47,7 +47,7 @@ in the example below).
 
 #### layout.tsx
 
-```ts
+```tsx
 'use client'
 
 import PiwikProProvider from '@piwikpro/next-piwik-pro'
@@ -56,17 +56,17 @@ export default function RootLayout({children}: {
   children: React.ReactNode
 }) {
   return (
-    <html lang = "en" >
-    <body>
-      <PiwikProProvider
-        containerId = "container-id"
-  containerUrl = "container-url"
-    >
-    {children}
-    < /PiwikProProvider>
-    < /body>
-    < /html>
-)
+    <html lang="en">
+      <body>
+        <PiwikProProvider
+          containerId="container-id"
+          containerUrl="container-url"
+        > 
+          {children}
+        </PiwikProProvider>
+      </body>
+    </html>
+  )
 }
 ```
 
@@ -85,7 +85,7 @@ NEXT_PUBLIC_CONTAINER_URL=https://example.piwik.pro
 
 #### layout.tsx
 
-```ts
+```tsx
 'use client'
 
 import PiwikProProvider from '@piwikpro/next-piwik-pro'
@@ -94,17 +94,17 @@ export default function RootLayout({children}: {
   children: React.ReactNode
 }) {
   return (
-    <html lang = "en" >
-    <body>
-      <PiwikProProvider
-        containerUrl = {process.env.NEXT_PUBLIC_CONTAINER_URL}
-  containerId = {process.env.NEXT_PUBLIC_CONTAINER_ID}
-    >
-    {children}
-    < /PiwikProProvider>
-    < /body>
-    < /html>
-)
+    <html lang="en">
+      <body>
+        <PiwikProProvider
+          containerUrl = {process.env.NEXT_PUBLIC_CONTAINER_URL}
+          containerId = {process.env.NEXT_PUBLIC_CONTAINER_ID}
+        >
+          {children}
+        </PiwikProProvider>
+      </body>
+    </html>
+  )
 }
 ```
 
@@ -122,7 +122,7 @@ method.
 
 #### layout.tsx
 
-```ts
+```tsx
 'use client'
 
 import PiwikProProvider from '@piwikpro/next-piwik-pro'
@@ -131,18 +131,18 @@ export default function RootLayout({children}: {
   children: React.ReactNode
 }) {
   return (
-    <html lang = "en" >
-    <body>
-      <PiwikProProvider
-        containerId = "container-id"
-  containerUrl = "container-url"
-  nonce = "nonce-string"
-    >
-    {children}
-    < /PiwikProProvider>
-    < /body>
-    < /html>
-)
+    <html lang="en">
+      <body>
+        <PiwikProProvider
+          containerId="container-id"
+          containerUrl="container-url"
+          nonce="nonce-string"
+        >
+          {children}
+        </PiwikProProvider>
+      </body>
+    </html>
+  )
 }
 ```
 
@@ -167,26 +167,21 @@ You can use those methods in all hooks and props for ex. `useEffect` or `onClick
 
 ### useEffect
 
-```ts
+```tsx
 useEffect(() => {
   PageViews.trackPageView('optional title')
 }, [])
 ```
 
 ### onClick
 
-```ts
-<button
-  onClick = {()
-=>
-{
+```tsx
+<button onClick = {() => {
   CustomEvent.trackEvent('Post', pageData.title)
-}
-}
->
+}}>
 CustomEvent.trackEvent
 button
-< /button>
+</button>
 ```
 
 Below you can view the sample usage of the available methods from modules.
@@ -316,94 +311,61 @@ Collection of methods to handle e-commerce events through the Piwik PRO API.
 
 ##### Methods
 
-- `eCommerce.addEcommerceItem(productSKU[, productName[, productCategory[, productPrice[, productQuantity]]]])` - Adds a
-  product to a virtual shopping cart. If a product with the same SKU is in the cart, it will be removed first. Does not
-  send any data to the Collecting & Processing Pipeline.
-
-    - `productSKU (string)` – Required Product stock-keeping unit
-    - `productName (string)` – Optional Product name
-    - `productCategory (string|Array<string>)` – Optional Product category or an array of up to 5 categories
-    - `productPrice (number)` – Optional Product price
-    - `productQuantity (number)` – Optional The number of units
-
-- `eCommerce.removeEcommerceItem(productSKU)` - Removes a product with the provided SKU from a virtual shopping cart. If
-  multiple units of that product are in the virtual cart, all of them will be removed. Does not send any data to the
-  Collecting & Processing Pipeline.
-
-    - `productSKU (string)` – Required stock-keeping unit of a product to remove
-
-- `eCommerce.clearEcommerceCart()` - Removes all items from a virtual shopping cart. Does not send any data to the
-  Collecting & Processing Pipeline.
-
-- `eCommerce.getEcommerceItems()` - Returns a copy of items from a virtual shopping cart. Does not send any data to the
-  Collecting & Processing Pipeline. Returns: Object containing all tracked items (
-  format: `Object<productSKU, Array[productSKU, productName, productCategory, price, quantity]>`)
-
-- `eCommerce.setEcommerceView([productSKU[, productName[, productCategory[, productPrice]]]])` - Tracks product or
-  category view. Must be followed by a page view.
-
-    - `productSKU (string)` – Optional Product stock-keeping unit
-    - `productName (string)` – Optional Product name
-    - `productCategory (string|Array<string>)` – Optional Category or an array of up to 5 categories
-    - `productPrice (number)` – Optional Product price
-
-- `eCommerce.trackEcommerceCartUpdate(cartAmount)` - Tracks items present in a virtual shopping cart (registered with
-  addEcommerceItem).
-
-    - `cartAmount` (number) – Required The total value of items in the cart
-
-- `eCommerce.trackEcommerceOrder(orderID, orderGrandTotal[, orderSubTotal[, orderTax[, orderShipping[, orderDiscount]]]])` -
-  Tracks a successfully placed e-commerce order with items present in a virtual cart (registered using
-  addEcommerceItem).
-    - `orderID (string)` – Required String uniquely identifying an order
-    - `orderGrandTotal (number)` – Required Order Revenue grand total - tax, shipping and discount included
-    - `orderSubTotal (number)`– Optional Order subtotal - without shipping
-    - `orderTax (number)`– Optional Order tax amount
-    - `orderShipping (number)` – Optional Order shipping cost
-    - `orderDiscount (number)` – Optional Order discount amount
+#### Methods
+* `ecommerceAddToCart(products: Product[])` - Tracks action of adding products to a cart.
+* `ecommerceRemoveFromCart(products: Product[])` - Tracks action of removing a products from a cart.
+* `ecommerceOrder(products: Product[], paymentInformation: PaymentInformation)` - Tracks conversion (including products and payment details).
+* `ecommerceCartUpdate(products: Product[], grandTotal: PaymentInformation['grandTotal'])` - Tracks current state of a cart.
+* `ecommerceProductDetailView(products: Product[])` - Tracks product or category view. Must be followed by a page view.discount amount
 
 ##### Example usage
 
 ```ts
-const {eCommerce} = usePiwikPro()
-
-eCommerce.addEcommerceItem('1', 'ProductName', 'Items', 69, 1)
-
-eCommerce.removeEcommerceItem('1')
-
-eCommerce.trackEcommerceOrder('id', 50)
-
-eCommerce.trackEcommerceCartUpdate(2)
-
-eCommerce.setEcommerceView('1')
-
-eCommerce.clearEcommerceCart()
-```
-
-Some of the methods are getting data from the API and they need to be called asynchronously. They provide data that can
-be shown no the page. This need to be done with defining async function in your hook body and setting the state of the
-variable. Like on example below.
+const { eCommerce } = usePiwikPro()
+
+const products = [{
+  sku: 'sku-4',
+  name: 'Product 4',
+  category: ['product-category', 'product-category-4'],
+  brand: 'Brand 4',
+  variant: 'Variant 4',
+  price: 39.96,
+  customDimensions: {
+    dimension1: 'value1',
+    dimension2: 'value2'
+  }
+}]
+
+const subTotal = products.reduce((acc, product) => {
+  if (product.price) {
+    return acc + product.price
+  }
+  return acc
+}, 0)
+
+const tax = 10
+const shipping = 4
+const discount = 5
+
+const paymentInformation: PaymentInformation = {
+  orderId: 'order-123',
+  grandTotal: subTotal + tax + shipping - discount,
+  subTotal,
+  tax,
+  shipping,
+  discount
+}
 
-```ts
-const {eCommerce} = usePiwikPro()
+eCommerce.ecommerceAddToCart(products)
 
-const [eCommerceItems, setECommerceInfo] = useState<any>('')
+eCommerce.ecommerceRemoveFromCart(products)
 
-const callAsyncMethods = async () => {
-  const ecItem = await eCommerce.getEcommerceItems()
-  setECommerceInfo(ecItem)
-}
+ecommerce.ecommerceOrder(products, paymentInformation)
 
-callAsyncMethods()
-```
+eCommerce.ecommerceCartUpdate(products, paymentInformation.grandTotal)
 
-You have access to those variables in you page body. Example below.
+eCommerce.ecommerceProductDetailView(products)
 
-```html
-<p>
-    <code>eCommerce.getEcommerceItems()</code> -{' '}
-    {JSON.stringify(eCommerceItems)}
-</p>
 ```
 
 #### Content Tracking