Merge develop into master

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `laravel-tagmanager` will be documented in this file.
 
+## 1.3 - 2022-01-27
+
+- Ecommerce events added
+
+## 1.2 - 2022-01-27
+
+- Laravel 9 support added
+
+## 1.1 - 2021-12-23
+
+- User-ID Middleware added
+
 ## 1.0 - 2021-12-22
 
 - Initial release

README.md

@@ -13,6 +13,10 @@ An easier way to add Google Tag Manager to your Laravel application. Including r
 - [Usage](#usage)
  - [Events](#events)
  - [User-ID](#user-id)
+ - [Ecommerce (GA4)](#ecommerce-ga4)
+ - [Ecommerce Item](#ecommerce-item)
+ - [Ecommerce Events](#ecommerce-events)
+ - [Ecommerce (UA)](#ecommerce-ua)
 - [Tests](#tests)
 - [License](#license)
 
@@ -127,7 +131,109 @@ protected $middlewareGroups = [
 
 By default the 'id' of the User model will be used. You change the key in ``config/tagmanager.php``.
 
-You can find more information about this feature on: ``https://developers.google.com/analytics/devguides/collection/ga4/user-id?technology=tagmanager``
+More information: ``https://developers.google.com/analytics/devguides/collection/ga4/user-id?technology=tagmanager``
+
+### Ecommerce (GA4)
+
+You can use the following snippets to trigger an Ecommerce event with Google Analytics 4 (GA4).
+
+#### Ecommerce item
+
+The ``TagManagerItem`` class allows you to easily create an Ecommerce item. You can set extra parameters with dynamic calls. Method names are used as keys and automatically converted to underscore case.
+
+```php
+use Label84\TagManager\TagManagerItem;
+
+new TagManagerItem(string $id, string $name, float $price, float $quantity);
+```
+
+##### Example: create item
+
+```php
+use Label84\TagManager\TagManagerItem;
+
+$item1 = new TagManagerItem('12345', 'Triblend Android T-Shirt', 15.25, 1);
+$item1->itemBrand('Google') // will add the item parameter { item_brand: 'Google' }
+ ->itemCategory('Apparel') // will add the item parameter { item_category: 'Apparel' }
+ ->itemVariant('Gray'); // will add the item parameter { item_variant: 'Gray' }
+```
+
+#### Ecommerce events
+
+The items parameter can be a single ``TagManagerItem`` item or an array of ``TagManagerItem`` items. You can also use plain arrays if you don't want to use the TagManagerItem class.
+
+```php
+use Label84\TagManager\Facades\TagManager;
+
+// Product views and interactions
+TagManager::viewItemList($items);
+TagManager::viewItem($items);
+TagManager::selectItem($items);
+
+// Promotion views and interactions
+TagManager::viewPromotion($items);
+TagManager::selectPromotion($items);
+
+// Pre-purchase interactions
+TagManager::addToWishList(string $currency, float $value, $items);
+TagManager::addToCart($items);
+TagManager::removeFromCart($items);
+TagManager::viewCart(string $currency, float $value, $items);
+
+// Purchases, checkouts, and refunds
+TagManager::beginCheckout($items);
+TagManager::addPaymentInfo(string $currency, float $value, string $paymentType, $items, string $coupon = '');
+TagManager::addShippingInfo(string $currency, float $value, string $shippingTier, $items, string $coupon = '');
+TagManager::purchase(string $transactionId, string $affiliation, string $currency, float $value, float $tax, float $shipping, $items, string $coupon = '');
+TagManager::refund(string $transactionId, string $affiliation, string $currency, float $value, float $tax, float $shipping, $items, string $coupon = '');
+```
+
+##### Example: call event with item
+
+```php
+use Label84\TagManager\Facades\TagManager;
+
+TagManager::purchase('00001', 'Google', 'EUR', 12.10, 2.10, 0, [
+ new TagManagerItem('12345', 'Triblend Android T-Shirt', 10.00, 1),
+]);
+```
+
+More information: ``https://developers.google.com/analytics/devguides/collection/ga4/ecommerce?client_type=gtm``
+
+### Ecommerce (UA)
+
+You can use the following snippet to trigger an Ecommerce purchase event with Universal Analytics (UA).
+
+```php
+use Label84\TagManager\Facades\TagManager;
+
+TagManager::push(['ecommerce' => [
+ 'purchase' => [
+ 'actionField' => [
+ 'id' => 'T12345',
+ 'affiliation' => 'Online Store',
+ 'revenue' => '35.43',
+ 'tax' => '4.90',
+ 'shipping' => '5.99',
+ 'coupon' => 'SUMMER_SALE',
+ ],
+ 'products' => [[
+ 'name' => 'Triblend Android T-Shirt',
+ 'id' => '12345',
+ 'price' => '15.25',
+ 'brand' => 'Google',
+ 'category' => 'Apparel',
+ 'variant' => 'Gray',
+ 'quantity' => 1,
+ 'coupon' => '',
+ ], [
+ // more items..
+ ]],
+ ],
+]]);
+```
+
+More information: ``https://developers.google.com/analytics/devguides/collection/ua/gtm/enhanced-ecommerce#purchases``
 
 ## Tests
 

composer.json

@@ -16,11 +16,6 @@
  "orchestra/testbench": "^6.0|^7.0",
  "nunomaduro/larastan": "^1.0"
  },
- "autoload": {
- "psr-4": {
- "Label84\\TagManager\\": "src"
- }
- },
  "extra": {
  "laravel": {
  "providers": [
@@ -30,6 +25,11 @@
  "TagManager": "Label84\\TagManager\\Facades\\TagManager"
  }
  }
+ }, 
+ "autoload": {
+ "psr-4": {
+ "Label84\\TagManager\\": "src"
+ }
  },
  "minimum-stability": "dev",
  "prefer-stable": true

phpstan.neon.dist

@@ -13,4 +13,6 @@ parameters:
 
  excludes_analyse:
 
- checkMissingIterableValueType: false
+ checkMissingIterableValueType: false
+
+ checkGenericClassInNonGenericObjectType: false

src/TagManager.php

@@ -20,6 +20,16 @@ public function push(array $variables): self
  return $this;
  }
 
+ public function get(): Collection
+ {
+ return $this->data;
+ }
+
+ public function clear(): void
+ {
+ $this->data = new Collection();
+ }
+
  public function event(string $name, array $variables = []): self
  {
  $this->data->push(['event' => $name] + $variables);
@@ -48,13 +58,193 @@ public function setUserId(string $userId): self
  return $this;
  }
 
- public function get(): Collection
+ /** @param TagManagerItem|array $items */
+ public function viewItemList($items, array $variables = []): self
  {
- return $this->data;
+ $this->event('view_item_list', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
  }
 
- public function clear(): void
+ /** @param TagManagerItem|array $items */
+ public function viewItem($items, array $variables = []): self
  {
- $this->data = new Collection();
+ $this->event('view_item', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function selectItem($items, array $variables = []): self
+ {
+ $this->event('select_item', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function viewPromotion($items, array $variables = []): self
+ {
+ $this->event('view_promotion', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function selectPromotion($items, array $variables = []): self
+ {
+ $this->event('select_promotion', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function addToWishlist(string $currency, float $value, $items, array $variables = []): self
+ {
+ $this->event('add_to_wishlist', array_merge(['ecommerce' => [
+ 'currency' => $currency,
+ 'value' => $value,
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function addToCart($items, array $variables = []): self
+ {
+ $this->event('add_to_cart', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function removeFromCart($items, array $variables = []): self
+ {
+ $this->event('remove_from_cart', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function viewCart(string $currency, float $value, $items, array $variables = []): self
+ {
+ $this->event('view_cart', array_merge(['ecommerce' => [
+ 'currency' => $currency,
+ 'value' => $value,
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function beginCheckout($items, array $variables = []): self
+ {
+ $this->event('begin_checkout', array_merge(['ecommerce' => [
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function addPaymentInfo(string $currency, float $value, string $paymentType, $items, string $coupon = '', array $variables = []): self
+ {
+ $this->event('add_payment_info', array_merge(['ecommerce' => [
+ 'currency' => $currency,
+ 'value' => $value,
+ 'coupon' => $coupon,
+ 'payment_type' => $paymentType,
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function addShippingInfo(string $currency, float $value, string $shippingTier, $items, string $coupon = '', array $variables = []): self
+ {
+ $this->event('add_shipping_info', array_merge(['ecommerce' => [
+ 'currency' => $currency,
+ 'value' => $value,
+ 'coupon' => $coupon,
+ 'shipping_tier' => $shippingTier,
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function purchase(string $transactionId, string $affiliation, string $currency, float $value, float $tax, float $shipping, $items, string $coupon = '', array $variables = []): self
+ {
+ $this->event('purchase', array_merge(['ecommerce' => [
+ 'transaction_id' => $transactionId,
+ 'affiliation' => $affiliation,
+ 'currency' => $currency,
+ 'value' => $value,
+ 'tax' => $tax,
+ 'shipping' => $shipping,
+ 'coupon' => $coupon,
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ public function refund(string $transactionId, string $affiliation, string $currency, float $value, float $tax, float $shipping, $items, string $coupon = '', array $variables = []): self
+ {
+ $this->event('refund', array_merge(['ecommerce' => [
+ 'transaction_id' => $transactionId,
+ 'affiliation' => $affiliation,
+ 'currency' => $currency,
+ 'value' => $value,
+ 'tax' => $tax,
+ 'shipping' => $shipping,
+ 'coupon' => $coupon,
+ 'items' => $this->formatItems($items),
+ ]], $variables));
+
+ return $this;
+ }
+
+ /** @param TagManagerItem|array $items */
+ private function formatItems($items): array
+ {
+ if ($items instanceof TagManagerItem) {
+ return [$items->toArray()];
+ }
+
+ if (isset($items['item_id']) || isset($items['item_name'])) {
+ return [$items];
+ }
+
+ $array = [];
+
+ foreach ($items as $item) {
+ if ($item instanceof TagManagerItem) {
+ array_push($array, $item->toArray());
+ } else {
+ array_push($array, $item);
+ }
+ }
+
+ return $array;
  }
 }