Merge pull request #3 from Promatur/ecommerce

eCommerce Tracking

Core/AnalyticsConfig.php

@@ -34,6 +34,13 @@ class AnalyticsConfig
      */
     public static $assets = "assets";
 
+    /**
+     * The default currency for all ECommerce events.
+     *
+     * @var string EUR, USD, GBP, ...
+     */
+    public static $currency = "USD";
+
     /**
      * Your preferred analytics handler. Possible options: 'auto', 'matomo', 'google analytics'.
      *

Core/AnalyticsHandler.php

@@ -4,6 +4,9 @@
 namespace ScAnalytics\Core;
 
 
+use ScAnalytics\Core\ECommerce\Product;
+use ScAnalytics\Core\ECommerce\Transaction;
+
 /**
  * Interface AnalyticsHandler. This interface creates a simple interface for all integrated analytics handlers. This interface maps different functions to the specific parameters of the analytics handlers.
  *
@@ -113,4 +116,58 @@ public function logout(): ARequest;
      */
     public function download(string $fileName, ?int $size = null): ARequest;
 
+    // - ECommerce
+    /**
+     * Sent, when adding one or more products to a shopping cart.
+     *
+     * @param Product[] $products A list of products, which are added to the cart. Keys are their position starting with <code>0</code>
+     * @return ARequest The analytics request
+     */
+    public function addCart(array $products): ARequest;
+
+    /**
+     * Sent, when removing one or more products from a shopping cart.
+     *
+     * @param Product[] $products A list of products, which are removed from the cart. Keys are their position starting with <code>0</code>
+     * @return ARequest The analytics request
+     */
+    public function removeCart(array $products): ARequest;
+
+    /**
+     * Sent, when a purchase is completed.
+     *
+     * @param Transaction $transaction The completed transaction
+     * @return ARequest The analytics request
+     */
+    public function purchase(Transaction $transaction): ARequest;
+
+    /**
+     * Sent, starting or proceeding in a checkout process. Is sent as the initial page view request.
+     * @param PageData|null $pageData The data of the page
+     * @param Product[] $products A list of products, which are added to the cart. Keys are their position starting with <code>0</code>
+     * @param int $step The step number
+     * @param string|null $option Additional information about a checkout step
+     * @return ARequest The analytics request
+     */
+    public function checkoutStep(?PageData $pageData, array $products, int $step, ?string $option = null): ARequest;
+
+    /**
+     * Measures a click on a product.
+     *
+     * @param string $listName The list, where the product is displayed
+     * @param Product $product The product, which the user clicked on
+     * @param int $productPosition The position of the product in the list
+     * @return ARequest The analytics request
+     */
+    public function productClick(string $listName, Product $product, int $productPosition = 1): ARequest;
+
+    /**
+     * Measures the view of a product page.
+     *
+     * @param Product $product The product, which is viewed
+     * @param PageData|null $pageData The data of the viewed page
+     * @return ARequest The analytics request
+     */
+    public function productPage(Product $product, ?PageData $pageData = null): ARequest;
+
 }

Core/ECommerce/Product.php

@@ -0,0 +1,175 @@
+<?php
+
+namespace ScAnalytics\Core\ECommerce;
+
+use Money\Money;
+
+/**
+ * Class Product. Represents a product to be sold.
+ *
+ * @author Jan-Nicklas Adler
+ * @version 1.0.0
+ * @license http://www.gnu.org/licenses/lgpl.html LGPL v3 or later
+ * @copyright All Rights Reserved.
+ */
+class Product
+{
+
+    /**
+     * @var string ID or SKU
+     */
+    private $id;
+
+    /**
+     * @var string|null A unique key for the product
+     */
+    private $key;
+
+    /**
+     * @var string|null The name of the product
+     */
+    private $name;
+
+    /**
+     * @var string|null A category for the product
+     */
+    private $category;
+
+    /**
+     * @var string|null A variant for the product
+     */
+    private $variant;
+
+    /**
+     * @var string|null A brand for the product
+     */
+    private $brand;
+
+    /**
+     * @var Money|null The original price of the product
+     */
+    private $price;
+
+    /**
+     * @var Money|null A final price, after discounts and taxes
+     */
+    private $finalPrice;
+
+    /**
+     * @var int|null The quantity of the product in the cart or checkout process
+     */
+    private $quantity;
+
+    /**
+     * @var string|null A coupon code applied to the product
+     */
+    private $coupon;
+
+    /**
+     * @param string $id ID or SKU
+     * @param Money|null $price The original price of the product
+     * @param Money|null $finalPrice A final price, after discounts and taxes
+     * @param string|null $key A unique key for the product
+     * @param string|null $name The name of the product
+     * @param string|null $category A category for the product
+     * @param string|null $variant A variant for the product
+     * @param string|null $brand A brand for the product
+     * @param int|null $quantity The quantity of the product in the cart or checkout process
+     * @param string|null $coupon A coupon code applied to the product
+     */
+    public function __construct(string $id, ?Money $price = null, ?Money $finalPrice = null, ?string $key = null, ?string $name = null, ?string $category = null, ?string $variant = null, ?string $brand = null, ?int $quantity = null, ?string $coupon = null)
+    {
+        $this->id = $id;
+        $this->key = $key;
+        $this->name = $name;
+        $this->category = $category;
+        $this->variant = $variant;
+        $this->brand = $brand;
+        $this->price = $price;
+        $this->finalPrice = $finalPrice;
+        $this->quantity = $quantity;
+        $this->coupon = $coupon;
+    }
+
+
+    /**
+     * @return string ID or SKU
+     */
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    /**
+     * @return string|null A unique key for the product
+     */
+    public function getKey(): ?string
+    {
+        return $this->key;
+    }
+
+    /**
+     * @return string|null The name of the product
+     */
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    /**
+     * @return string|null A category for the product
+     */
+    public function getCategory(): ?string
+    {
+        return $this->category;
+    }
+
+    /**
+     * @return string|null A variant for the product
+     */
+    public function getVariant(): ?string
+    {
+        return $this->variant;
+    }
+
+    /**
+     * @return string|null A brand for the product
+     */
+    public function getBrand(): ?string
+    {
+        return $this->brand;
+    }
+
+    /**
+     * @return Money|null The original price of the product
+     */
+    public function getPrice(): ?Money
+    {
+        return $this->price;
+    }
+
+    /**
+     * @return Money|null A final price, after discounts and taxes
+     */
+    public function getFinalPrice(): ?Money
+    {
+        return $this->finalPrice;
+    }
+
+    /**
+     * @return int|null The quantity of the product in the cart or checkout process
+     */
+    public function getQuantity(): ?int
+    {
+        return $this->quantity;
+    }
+
+    /**
+     * @return string|null A coupon code applied to the product
+     */
+    public function getCoupon(): ?string
+    {
+        return $this->coupon;
+    }
+
+}

Core/ECommerce/ProductImpression.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace ScAnalytics\Core\ECommerce;
+
+use Money\Money;
+
+/**
+ * Class ProductImpression. Represents information about a product that has been viewed.
+ *
+ * @author Jan-Nicklas Adler
+ * @version 1.0.0
+ * @license http://www.gnu.org/licenses/lgpl.html LGPL v3 or later
+ * @copyright All Rights Reserved.
+ */
+class ProductImpression
+{
+
+    /**
+     * @var int The position of the product in the list
+     */
+    private $position;
+
+    /**
+     * @var Product The product that has been viewed
+     */
+    private $product;
+
+    /**
+     * @var array<int, string> A product-level custom dimension
+     */
+    private $dimensions;
+
+    /**
+     * @var array<int, int> A product-level custom metric
+     */
+    private $metrics;
+
+    /**
+     * @param int $position The position of the product in the list
+     * @param Product $product The product that has been viewed
+     * @param array<int, string> $dimensions A product-level custom dimension
+     * @param array<int, int> $metrics A product-level custom metric
+     */
+    public function __construct(int $position, Product $product, array $dimensions = [], array $metrics = [])
+    {
+        $this->position = $position;
+        $this->product = $product;
+        $this->dimensions = $dimensions;
+        $this->metrics = $metrics;
+    }
+
+    /**
+     * @return int The position of the product in the list
+     */
+    public function getPosition(): int
+    {
+        return $this->position;
+    }
+
+    /**
+     * @return Product The product that has been viewed
+     */
+    public function getProduct(): Product
+    {
+        return $this->product;
+    }
+
+    /**
+     * @return array<int, string> A product-level custom dimension
+     */
+    public function getDimensions(): array
+    {
+        return $this->dimensions;
+    }
+
+    /**
+     * @return array<int, int> The product-level custom metric
+     */
+    public function getMetrics(): array
+    {
+        return $this->metrics;
+    }
+
+}