├── .gitignore
├── src
    ├── Contracts
    │   ├── MapsToDataLayer.php
    │   └── MapsToFacebookPixel.php
    ├── Objects
    │   ├── DefaultUserData.php
    │   └── PageViewEvent.php
    ├── View
    │   └── Components
    │   │   ├── DataLayerPageView.php
    │   │   ├── FacebookPixelPageView.php
    │   │   ├── DataLayerVariable.php
    │   │   ├── GoogleTagManagerBody.php
    │   │   ├── GoogleTagManagerHead.php
    │   │   ├── FacebookPixelTrackingEvent.php
    │   │   ├── DataLayerUserDataVariable.php
    │   │   └── FacebookPixelScript.php
    ├── Collections
    │   └── EventCollection.php
    ├── Facades
    │   └── ConversionsApi.php
    ├── ConversionsApi.php
    └── ConversionsApiServiceProvider.php
├── resources
    └── views
    │   └── components
    │       ├── google-tag-manager-body.blade.php
    │       ├── data-layer-variable.blade.php
    │       ├── facebook-pixel-tracking-event.blade.php
    │       ├── google-tag-manager-head.blade.php
    │       └── facebook-pixel-script.blade.php
├── tests
    ├── TestCase.php
    ├── Support
    │   └── Events
    │   │   ├── ContactEvent.php
    │   │   └── PurchaseEvent.php
    ├── Unit
    │   ├── Objects
    │   │   └── PageViewEventTest.php
    │   └── Collections
    │   │   └── EventCollectionTest.php
    └── Feature
    │   ├── View
    │       └── Components
    │       │   ├── DataLayerUserDataVariableTest.php
    │       │   ├── GoogleTagManagerBodyTest.php
    │       │   ├── GoogleTagManagerHeadTest.php
    │       │   ├── FacebookPixelPageViewTest.php
    │       │   ├── DataLayerPageViewTest.php
    │       │   ├── DataLayerVariableTest.php
    │       │   ├── FacebookPixelScriptTest.php
    │       │   └── FacebookPixelTrackingEventTest.php
    │   └── ConversionsApiTest.php
├── phpunit.xml
├── config
    └── conversions-api.php
├── .github
    ├── pull_request_template.md
    └── workflows
    │   └── main.yml
├── LICENSE.md
├── .php-cs-fixer.php
├── composer.json
├── UPGRADING.md
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
1 | vendor
2 | composer.lock
3 | .phpunit.result.cache
4 | .php-cs-fixer.cache
5 | .phpunit.cache


--------------------------------------------------------------------------------
/src/Contracts/MapsToDataLayer.php:
--------------------------------------------------------------------------------
1 | <?php
2 | 
3 | namespace Esign\ConversionsApi\Contracts;
4 | 
5 | interface MapsToDataLayer
6 | {
7 |     public function getDataLayerArguments(): array;
8 | }
9 | 


--------------------------------------------------------------------------------
/resources/views/components/google-tag-manager-body.blade.php:
--------------------------------------------------------------------------------
1 | <noscript><iframe src="https://www.googletagmanager.com/ns.html?id={{ $gtmId }}"
2 | height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>


--------------------------------------------------------------------------------
/resources/views/components/data-layer-variable.blade.php:
--------------------------------------------------------------------------------
1 | @props(['arguments'])
2 | 
3 | <script {{ $attributes }}>
4 |     window.dataLayer = window.dataLayer || [];
5 |     window.dataLayer.push(@json((object) $arguments));
6 | </script>


--------------------------------------------------------------------------------
/resources/views/components/facebook-pixel-tracking-event.blade.php:
--------------------------------------------------------------------------------
 1 | @props([
 2 |     'eventType',
 3 |     'eventName',
 4 |     'customData',
 5 |     'eventData',
 6 | ])
 7 | 
 8 | <script {{ $attributes }}>
 9 |     fbq('{{ $eventType }}', '{{ $eventName }}', @json((object) $customData), @json((object) $eventData));
10 | </script>


--------------------------------------------------------------------------------
/tests/TestCase.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests;
 4 | 
 5 | use Esign\ConversionsApi\ConversionsApiServiceProvider;
 6 | use Orchestra\Testbench\TestCase as BaseTestCase;
 7 | 
 8 | class TestCase extends BaseTestCase
 9 | {
10 |     protected function getPackageProviders($app)
11 |     {
12 |         return [ConversionsApiServiceProvider::class];
13 |     }
14 | }
15 | 


--------------------------------------------------------------------------------
/src/Contracts/MapsToFacebookPixel.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Contracts;
 4 | 
 5 | interface MapsToFacebookPixel
 6 | {
 7 |     public function getFacebookPixelEventType(): string;
 8 | 
 9 |     public function getFacebookPixelEventName(): string;
10 | 
11 |     public function getFacebookPixelCustomData(): array;
12 | 
13 |     public function getFacebookPixelEventData(): array;
14 | }
15 | 


--------------------------------------------------------------------------------
/resources/views/components/google-tag-manager-head.blade.php:
--------------------------------------------------------------------------------
1 | <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
2 | new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
3 | j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
4 | 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
5 | })(window,document,'script','dataLayer','{{ $gtmId }}');</script>


--------------------------------------------------------------------------------
/tests/Support/Events/ContactEvent.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Support\Events;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToDataLayer;
 6 | use FacebookAds\Object\ServerSide\Event;
 7 | 
 8 | class ContactEvent extends Event implements MapsToDataLayer
 9 | {
10 |     public function getDataLayerArguments(): array
11 |     {
12 |         return [
13 |             'event' => 'Contact',
14 |             'conversionsApiContactEventId' => $this->getEventId(),
15 |         ];
16 |     }
17 | }
18 | 


--------------------------------------------------------------------------------
/src/Objects/DefaultUserData.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Objects;
 4 | 
 5 | use FacebookAds\Object\ServerSide\UserData;
 6 | 
 7 | class DefaultUserData extends UserData
 8 | {
 9 |     public static function create(): self
10 |     {
11 |         return (new self())
12 |             ->setFbp(request()->cookie('_fbp'))
13 |             ->setFbc(request()->cookie('_fbc'))
14 |             ->setClientIpAddress(request()->ip())
15 |             ->setClientUserAgent(request()->userAgent());
16 |     }
17 | }
18 | 


--------------------------------------------------------------------------------
/src/View/Components/DataLayerPageView.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Esign\ConversionsApi\Facades\ConversionsApi;
 6 | use Esign\ConversionsApi\Objects\PageViewEvent;
 7 | 
 8 | class DataLayerPageView extends DataLayerVariable
 9 | {
10 |     public function __construct()
11 |     {
12 |         $pageViewEvent = PageViewEvent::create();
13 |         ConversionsApi::clearEvents()->addEvent($pageViewEvent)->sendEvents();
14 | 
15 |         parent::__construct($pageViewEvent);
16 |     }
17 | }
18 | 


--------------------------------------------------------------------------------
/src/View/Components/FacebookPixelPageView.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Esign\ConversionsApi\Facades\ConversionsApi;
 6 | use Esign\ConversionsApi\Objects\PageViewEvent;
 7 | 
 8 | class FacebookPixelPageView extends FacebookPixelTrackingEvent
 9 | {
10 |     public function __construct()
11 |     {
12 |         $pageViewEvent = PageViewEvent::create();
13 |         ConversionsApi::clearEvents()->addEvent($pageViewEvent)->sendEvents();
14 | 
15 |         parent::__construct($pageViewEvent);
16 |     }
17 | }
18 | 


--------------------------------------------------------------------------------
/src/View/Components/DataLayerVariable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToDataLayer;
 6 | use Illuminate\View\Component;
 7 | 
 8 | class DataLayerVariable extends Component
 9 | {
10 |     public function __construct(
11 |         protected MapsToDataLayer $event
12 |     ) {
13 |     }
14 | 
15 |     public function render()
16 |     {
17 |         return view('conversions-api::components.data-layer-variable', [
18 |             'arguments' => $this->event->getDataLayerArguments(),
19 |         ]);
20 |     }
21 | }
22 | 


--------------------------------------------------------------------------------
/src/View/Components/GoogleTagManagerBody.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Illuminate\View\Component;
 6 | 
 7 | class GoogleTagManagerBody extends Component
 8 | {
 9 |     protected ?string $gtmId;
10 | 
11 |     public function __construct(?string $gtmId = null)
12 |     {
13 |         $this->gtmId = $gtmId ?? config('conversions-api.gtm_id');
14 |     }
15 | 
16 |     public function render()
17 |     {
18 |         return view('conversions-api::components.google-tag-manager-body', [
19 |             'gtmId' => $this->gtmId,
20 |         ]);
21 |     }
22 | }


--------------------------------------------------------------------------------
/src/View/Components/GoogleTagManagerHead.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Illuminate\View\Component;
 6 | 
 7 | class GoogleTagManagerHead extends Component
 8 | {
 9 |     protected ?string $gtmId;
10 | 
11 |     public function __construct(?string $gtmId = null)
12 |     {
13 |         $this->gtmId = $gtmId ?? config('conversions-api.gtm_id');
14 |     }
15 | 
16 |     public function render()
17 |     {
18 |         return view('conversions-api::components.google-tag-manager-head', [
19 |             'gtmId' => $this->gtmId,
20 |         ]);
21 |     }
22 | }


--------------------------------------------------------------------------------
/src/Collections/EventCollection.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Collections;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToDataLayer;
 6 | use Esign\ConversionsApi\Contracts\MapsToFacebookPixel;
 7 | use Illuminate\Support\Collection;
 8 | 
 9 | class EventCollection extends Collection
10 | {
11 |     public function filterFacebookPixelEvents(): static
12 |     {
13 |         return $this->filter(fn ($event) => $event instanceof MapsToFacebookPixel);
14 |     }
15 | 
16 |     public function filterDataLayerEvents(): static
17 |     {
18 |         return $this->filter(fn ($event) => $event instanceof MapsToDataLayer);
19 |     }
20 | }
21 | 


--------------------------------------------------------------------------------
/resources/views/components/facebook-pixel-script.blade.php:
--------------------------------------------------------------------------------
 1 | @props([
 2 |     'pixelId',
 3 |     'advancedMatchingData',
 4 | ])
 5 | 
 6 | <script {{ $attributes }}>
 7 |     !function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
 8 |     n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
 9 |     n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
10 |     t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
11 |     document,'script','https://connect.facebook.net/en_US/fbevents.js');
12 | 
13 |     fbq('init', '{{ $pixelId }}', @json((object) $advancedMatchingData));
14 | </script>


--------------------------------------------------------------------------------
/phpunit.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0" encoding="UTF-8"?>
 2 | <phpunit
 3 |     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 4 |     bootstrap="vendor/autoload.php"
 5 |     backupGlobals="false"
 6 |     colors="true"
 7 |     processIsolation="false"
 8 |     stopOnFailure="false"
 9 |     xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
10 |     cacheDirectory=".phpunit.cache"
11 |     backupStaticProperties="false"
12 | >
13 |   <testsuites>
14 |     <testsuite name="Esign Test Suite">
15 |       <directory>tests</directory>
16 |     </testsuite>
17 |   </testsuites>
18 |   <php>
19 |     <env name="DB_CONNECTION" value="testing"/>
20 |   </php>
21 |   <source>
22 |     <include>
23 |       <directory suffix=".php">src/</directory>
24 |     </include>
25 |   </source>
26 | </phpunit>
27 | 


--------------------------------------------------------------------------------
/src/View/Components/FacebookPixelTrackingEvent.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToFacebookPixel;
 6 | use Illuminate\View\Component;
 7 | 
 8 | class FacebookPixelTrackingEvent extends Component
 9 | {
10 |     public function __construct(
11 |         protected MapsToFacebookPixel $event
12 |     ) {
13 |     }
14 | 
15 |     public function render()
16 |     {
17 |         return view('conversions-api::components.facebook-pixel-tracking-event', [
18 |             'eventType' => $this->event->getFacebookPixelEventType(),
19 |             'eventName' => $this->event->getFacebookPixelEventName(),
20 |             'customData' => $this->event->getFacebookPixelCustomData(),
21 |             'eventData' => $this->event->getFacebookPixelEventData(),
22 |         ]);
23 |     }
24 | }
25 | 


--------------------------------------------------------------------------------
/config/conversions-api.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | return [
 4 |     /**
 5 |      * The access token used by the Conversions API.
 6 |      */
 7 |     'access_token' => env('CONVERSIONS_API_ACCESS_TOKEN'),
 8 | 
 9 |     /**
10 |      * The pixel ID used by the Conversions API.
11 |      */
12 |     'pixel_id' => env('CONVERSIONS_API_PIXEL_ID'),
13 | 
14 |     /**
15 |      * The Google Tag Manager container ID used in case you're deduplicating
16 |      * events through Google Tag Manager instead of Facebook Pixel directly.
17 |      * Should look something like "GTM-XXXXXX".
18 |      */
19 |     'gtm_id' => env('GOOGLE_TAG_MANAGER_ID'),
20 | 
21 |     /**
22 |      * The Conversions API comes with a nice way to test your events.
23 |      * You may use this config variable to set your test code.
24 |      */
25 |     'test_code' => env('CONVERSIONS_API_TEST_CODE'),
26 | ];
27 | 


--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
 1 | 
 2 | ## Description
 3 | <!-- Provide a brief description of the changes or additions in this pull request. -->
 4 | 
 5 | ## How has this been tested?
 6 | - [ ] Unit tests
 7 | - [ ] Integration tests
 8 | - [ ] Manual testing
 9 | 
10 | ## Type of change
11 | - [ ] Bug fix
12 | - [ ] New feature
13 | - [ ] Breaking change
14 | - [ ] Documentation update
15 | - [ ] Other (please describe):
16 | 
17 | ## Checklist
18 | <!-- Please ensure that you have completed the following before submitting your pull request. Delete any tasks that are not applicable. -->
19 | 
20 | - [ ] I have performed a self-review of my own code.
21 | - [ ] I have commented my code, particularly in hard-to-understand areas.
22 | - [ ] I have made corresponding changes to the documentation if necessary.
23 | - [ ] I have added tests that prove my fix is effective or that my feature works.
24 | 


--------------------------------------------------------------------------------
/src/Facades/ConversionsApi.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Facades;
 4 | 
 5 | use Illuminate\Support\Facades\Facade;
 6 | 
 7 | /**
 8 |  * @method static self setUserData(\FacebookAds\Object\ServerSide\UserData $userData)
 9 |  * @method static \FacebookAds\Object\ServerSide\UserData getUserData()
10 |  * @method static self addEvent(\FacebookAds\Object\ServerSide\Event $event)
11 |  * @method static self addEvents(iterable $events)
12 |  * @method static self setEvents(iterable $events)
13 |  * @method static \Illuminate\Support\Collection getEvents()
14 |  * @method static self clearEvents()
15 |  * @method static \GuzzleHttp\Promise\PromiseInterface sendEvents()
16 |  *
17 |  * @see \Esign\ConversionsApi\ConversionsApi
18 |  */
19 | class ConversionsApi extends Facade
20 | {
21 |     protected static function getFacadeAccessor(): string
22 |     {
23 |         return \Esign\ConversionsApi\ConversionsApi::class;
24 |     }
25 | }
26 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) Esign <hello@esign.eu>
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.


--------------------------------------------------------------------------------
/tests/Unit/Objects/PageViewEventTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Unit\Objects;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Facades\ConversionsApi;
 7 | use Esign\ConversionsApi\Objects\PageViewEvent;
 8 | use Esign\ConversionsApi\Tests\TestCase;
 9 | use FacebookAds\Object\ServerSide\ActionSource;
10 | use Illuminate\Support\Str;
11 | 
12 | final class PageViewEventTest extends TestCase
13 | {
14 |     #[Test]
15 |     public function it_can_statically_create_itself(): void
16 |     {
17 |         $this->get('posts?title=abc');
18 |         Str::createUuidsUsing(fn () => 'b13ddf8f-df2d-4554-9ae6-a1a73861b0ad');
19 | 
20 |         $event = PageViewEvent::create();
21 | 
22 |         $this->assertEquals(ActionSource::WEBSITE, $event->getActionSource());
23 |         $this->assertEquals('PageView', $event->getEventName());
24 |         $this->assertEquals('b13ddf8f-df2d-4554-9ae6-a1a73861b0ad', $event->getEventId());
25 |         $this->assertEquals(ConversionsApi::getUserData(), $event->getUserData());
26 |         $this->assertEquals('http://localhost/posts?title=abc', $event->getEventSourceUrl());
27 |     }
28 | }


--------------------------------------------------------------------------------
/tests/Feature/View/Components/DataLayerUserDataVariableTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Facades\ConversionsApi;
 7 | use Esign\ConversionsApi\Objects\DefaultUserData;
 8 | use Esign\ConversionsApi\Tests\Support\Events\ContactEvent;
 9 | use Esign\ConversionsApi\Tests\TestCase;
10 | use Esign\ConversionsApi\View\Components\DataLayerUserDataVariable;
11 | use Esign\ConversionsApi\View\Components\DataLayerVariable;
12 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
13 | 
14 | final class DataLayerUserDataVariableTest extends TestCase
15 | {
16 |     use InteractsWithViews;
17 | 
18 |     #[Test]
19 |     public function it_can_render_the_view(): void
20 |     {
21 |         ConversionsApi::setUserData(
22 |             DefaultUserData::create()->setEmail('test@test.com')
23 |         );
24 |         $component = $this->component(DataLayerUserDataVariable::class);
25 | 
26 |         $component->assertSee(
27 |             'window.dataLayer.push({"conversionsApiUserEmail":"test@test.com"});',
28 |             false
29 |         );
30 |     }
31 | }
32 | 


--------------------------------------------------------------------------------
/tests/Feature/View/Components/GoogleTagManagerBodyTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Tests\TestCase;
 7 | use Esign\ConversionsApi\View\Components\GoogleTagManagerBody;
 8 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
 9 | use Illuminate\Support\Facades\Config;
10 | 
11 | final class GoogleTagManagerBodyTest extends TestCase
12 | {
13 |     use InteractsWithViews;
14 | 
15 |     #[Test]
16 |     public function it_can_render_the_view(): void
17 |     {
18 |         Config::set('conversions-api.gtm_id', 'GTM-123456');
19 |         $component = $this->component(GoogleTagManagerBody::class);
20 | 
21 |         $component->assertSee('https://www.googletagmanager.com/ns.html?id=GTM-123456');
22 |     }
23 | 
24 |     #[Test]
25 |     public function it_can_render_the_view_using_custom_data(): void
26 |     {
27 |         Config::set('conversions-api.gtm_id', null);
28 |         $component = $this->component(GoogleTagManagerBody::class, [
29 |             'gtmId' => 'GTM-123456',
30 |         ]);
31 | 
32 |         $component->assertSee('https://www.googletagmanager.com/ns.html?id=GTM-123456');
33 |     }
34 | }


--------------------------------------------------------------------------------
/tests/Feature/View/Components/GoogleTagManagerHeadTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Tests\TestCase;
 7 | use Esign\ConversionsApi\View\Components\GoogleTagManagerHead;
 8 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
 9 | use Illuminate\Support\Facades\Config;
10 | 
11 | final class GoogleTagManagerHeadTest extends TestCase
12 | {
13 |     use InteractsWithViews;
14 | 
15 |     #[Test]
16 |     public function it_can_render_the_view(): void
17 |     {
18 |         Config::set('conversions-api.gtm_id', 'GTM-123456');
19 |         $component = $this->component(GoogleTagManagerHead::class);
20 | 
21 |         $component->assertSee("(window,document,'script','dataLayer','GTM-123456')", false);
22 |     }
23 | 
24 |     #[Test]
25 |     public function it_can_render_the_view_using_custom_data(): void
26 |     {
27 |         Config::set('conversions-api.gtm_id', null);
28 |         $component = $this->component(GoogleTagManagerHead::class, [
29 |             'gtmId' => 'GTM-123456',
30 |         ]);
31 | 
32 |         $component->assertSee("(window,document,'script','dataLayer','GTM-123456')", false);
33 |     }
34 | }


--------------------------------------------------------------------------------
/tests/Support/Events/PurchaseEvent.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Support\Events;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToFacebookPixel;
 6 | use FacebookAds\Object\ServerSide\Content;
 7 | use FacebookAds\Object\ServerSide\Event;
 8 | 
 9 | class PurchaseEvent extends Event implements MapsToFacebookPixel
10 | {
11 |     public function getFacebookPixelEventType(): string
12 |     {
13 |         return 'track';
14 |     }
15 | 
16 |     public function getFacebookPixelEventName(): string
17 |     {
18 |         return 'Purchase';
19 |     }
20 | 
21 |     public function getFacebookPixelCustomData(): array
22 |     {
23 |         $customData = $this->getCustomData();
24 | 
25 |         return array_filter([
26 |             'value' => $customData?->getValue(),
27 |             'currency' => $customData?->getCurrency(),
28 |             'contents' => array_map(function (Content $content) {
29 |                 return [
30 |                     'id' => $content->getProductId(),
31 |                     'quantity' => $content->getQuantity(),
32 |                 ];
33 |             }, $customData?->getContents() ?? []),
34 |         ]);
35 |     }
36 | 
37 |     public function getFacebookPixelEventData(): array
38 |     {
39 |         return array_filter(['eventID' => $this->getEventId()]);
40 |     }
41 | }
42 | 


--------------------------------------------------------------------------------
/src/View/Components/DataLayerUserDataVariable.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToDataLayer;
 6 | use Esign\ConversionsApi\Facades\ConversionsApi;
 7 | 
 8 | class DataLayerUserDataVariable extends DataLayerVariable implements MapsToDataLayer
 9 | {
10 |     public function __construct()
11 |     {
12 |         parent::__construct($this);
13 |     }
14 | 
15 |     public function getDataLayerArguments(): array
16 |     {
17 |         $userData = ConversionsApi::getUserData();
18 | 
19 |         return array_filter([
20 |             'conversionsApiUserEmail' => $userData->getEmail(),
21 |             'conversionsApiUserFirstName' => $userData->getFirstName(),
22 |             'conversionsApiUserLastName' => $userData->getLastName(),
23 |             'conversionsApiUserPhone' => $userData->getPhone(),
24 |             'conversionsApiUserExternalId' => $userData->getExternalId(),
25 |             'conversionsApiUserGender' => $userData->getGender(),
26 |             'conversionsApiUserDateOfBirth' => $userData->getDateOfBirth(),
27 |             'conversionsApiUserCity' => $userData->getCity(),
28 |             'conversionsApiUserState' => $userData->getState(),
29 |             'conversionsApiUserZipCode' => $userData->getZipCode(),
30 |             'conversionsApiUserCountry' => $userData->getCountryCode(),
31 |         ]);
32 |     }
33 | }


--------------------------------------------------------------------------------
/.php-cs-fixer.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | $finder = \PhpCsFixer\Finder::create()
 4 |     ->in([
 5 |         __DIR__ . '/src',
 6 |         __DIR__ . '/config',
 7 |         __DIR__ . '/tests',
 8 |     ])
 9 |     ->name('*.php')
10 |     ->notName('*.blade.php')
11 |     ->ignoreDotFiles(true)
12 |     ->ignoreVCS(true);
13 | 
14 | return (new PhpCsFixer\Config())
15 |     ->setRules([
16 |         '@PSR12' => true,
17 |         'array_syntax' => ['syntax' => 'short'],
18 |         'ordered_imports' => ['sort_algorithm' => 'alpha'],
19 |         'no_unused_imports' => true,
20 |         'not_operator_with_successor_space' => true,
21 |         'trailing_comma_in_multiline' => [
22 |             'elements' => ['arrays'],
23 |         ],
24 |         'unary_operator_spaces' => true,
25 |         'binary_operator_spaces' => true,
26 |         'blank_line_before_statement' => [
27 |             'statements' => ['break', 'continue', 'declare', 'return', 'throw', 'try'],
28 |         ],
29 |         'phpdoc_scalar' => true,
30 |         'phpdoc_single_line_var_spacing' => true,
31 |         'class_attributes_separation' => [
32 |             'elements' => [
33 |                 'method' => 'one',
34 |             ],
35 |         ],
36 |         'method_argument_space' => [
37 |             'on_multiline' => 'ensure_fully_multiline',
38 |             'keep_multiple_spaces_after_comma' => true,
39 |         ],
40 |         'single_trait_insert_per_statement' => true,
41 |     ])
42 |     ->setFinder($finder);
43 | 


--------------------------------------------------------------------------------
/tests/Unit/Collections/EventCollectionTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Unit\Collections;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Collections\EventCollection;
 7 | use Esign\ConversionsApi\Tests\Support\Events\ContactEvent;
 8 | use Esign\ConversionsApi\Tests\Support\Events\PurchaseEvent;
 9 | use Esign\ConversionsApi\Tests\TestCase;
10 | 
11 | final class EventCollectionTest extends TestCase
12 | {
13 |     #[Test]
14 |     public function it_can_filter_facebook_pixel_events(): void
15 |     {
16 |         $eventCollection = new EventCollection([
17 |             $purchaseEvent = new PurchaseEvent(),
18 |             $contactEvent = new ContactEvent(),
19 |         ]);
20 | 
21 |         $facebookPixelEvents = $eventCollection->filterFacebookPixelEvents();
22 | 
23 |         $this->assertTrue($facebookPixelEvents->contains($purchaseEvent));
24 |         $this->assertFalse($facebookPixelEvents->contains($contactEvent));
25 |     }
26 | 
27 |     #[Test]
28 |     public function it_can_filter_data_layer_events(): void
29 |     {
30 |         $eventCollection = new EventCollection([
31 |             $purchaseEvent = new PurchaseEvent(),
32 |             $contactEvent = new ContactEvent(),
33 |         ]);
34 | 
35 |         $dataLayerEvents = $eventCollection->filterDataLayerEvents();
36 | 
37 |         $this->assertFalse($dataLayerEvents->contains($purchaseEvent));
38 |         $this->assertTrue($dataLayerEvents->contains($contactEvent));
39 |     }
40 | }
41 | 


--------------------------------------------------------------------------------
/tests/Feature/View/Components/FacebookPixelPageViewTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\ConversionsApi;
 7 | use Esign\ConversionsApi\Tests\TestCase;
 8 | use Esign\ConversionsApi\View\Components\FacebookPixelPageView;
 9 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
10 | use Illuminate\Support\Str;
11 | use Mockery\MockInterface;
12 | 
13 | final class FacebookPixelPageViewTest extends TestCase
14 | {
15 |     use InteractsWithViews;
16 | 
17 |     #[Test]
18 |     public function it_can_render_the_view(): void
19 |     {
20 |         Str::createUuidsUsing(fn () => 'b13ddf8f-df2d-4554-9ae6-a1a73861b0ad');
21 |         $component = $this->component(FacebookPixelPageView::class);
22 | 
23 |         $component->assertSee(
24 |             "fbq('track', 'PageView', {}, {\"eventID\":\"b13ddf8f-df2d-4554-9ae6-a1a73861b0ad\"}",
25 |             false
26 |         );
27 |     }
28 | 
29 |     #[Test]
30 |     public function it_can_execute_a_page_view_event(): void
31 |     {
32 |         $this->mock(ConversionsApi::class, function (MockInterface $mock) {
33 |             $mock->shouldReceive('getUserData')->once();
34 |             $mock->shouldReceive('clearEvents')->once()->andReturnSelf();
35 |             $mock->shouldReceive('addEvent')->once()->andReturnSelf();
36 |             $mock->shouldReceive('sendEvents')->once();
37 |         });
38 | 
39 |         $this->component(FacebookPixelPageView::class);
40 |     }
41 | }
42 | 


--------------------------------------------------------------------------------
/tests/Feature/View/Components/DataLayerPageViewTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\ConversionsApi;
 7 | use Esign\ConversionsApi\Tests\TestCase;
 8 | use Esign\ConversionsApi\View\Components\DataLayerPageView;
 9 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
10 | use Illuminate\Support\Str;
11 | use Mockery\MockInterface;
12 | 
13 | final class DataLayerPageViewTest extends TestCase
14 | {
15 |     use InteractsWithViews;
16 | 
17 |     #[Test]
18 |     public function it_can_render_the_view(): void
19 |     {
20 |         Str::createUuidsUsing(fn () => 'b13ddf8f-df2d-4554-9ae6-a1a73861b0ad');
21 |         $component = $this->component(DataLayerPageView::class);
22 | 
23 |         $component->assertSee(
24 |             'window.dataLayer.push({"event":"conversionsApiPageView","conversionsApiPageViewEventId":"b13ddf8f-df2d-4554-9ae6-a1a73861b0ad"});',
25 |             false
26 |         );
27 |     }
28 | 
29 |     #[Test]
30 |     public function it_can_execute_a_page_view_event(): void
31 |     {
32 |         $this->mock(ConversionsApi::class, function (MockInterface $mock) {
33 |             $mock->shouldReceive('getUserData')->once();
34 |             $mock->shouldReceive('clearEvents')->once()->andReturnSelf();
35 |             $mock->shouldReceive('addEvent')->once()->andReturnSelf();
36 |             $mock->shouldReceive('sendEvents')->once();
37 |         });
38 | 
39 |         $this->component(DataLayerPageView::class);
40 |     }
41 | }
42 | 


--------------------------------------------------------------------------------
/src/Objects/PageViewEvent.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Objects;
 4 | 
 5 | use Esign\ConversionsApi\Contracts\MapsToDataLayer;
 6 | use Esign\ConversionsApi\Contracts\MapsToFacebookPixel;
 7 | use Esign\ConversionsApi\Facades\ConversionsApi;
 8 | use FacebookAds\Object\ServerSide\ActionSource;
 9 | use FacebookAds\Object\ServerSide\Event;
10 | use Illuminate\Support\Str;
11 | 
12 | class PageViewEvent extends Event implements MapsToFacebookPixel, MapsToDataLayer
13 | {
14 |     public static function create(): self
15 |     {
16 |         return (new self())
17 |             ->setActionSource(ActionSource::WEBSITE)
18 |             ->setEventName('PageView')
19 |             ->setEventId((string) Str::uuid())
20 |             ->setEventTime(time())
21 |             ->setEventSourceUrl(request()->fullUrl())
22 |             ->setUserData(ConversionsApi::getUserData());
23 |     }
24 | 
25 |     public function getFacebookPixelEventType(): string
26 |     {
27 |         return 'track';
28 |     }
29 | 
30 |     public function getFacebookPixelEventName(): string
31 |     {
32 |         return $this->getEventName();
33 |     }
34 | 
35 |     public function getFacebookPixelCustomData(): array
36 |     {
37 |         return [];
38 |     }
39 | 
40 |     public function getFacebookPixelEventData(): array
41 |     {
42 |         return ['eventID' => $this->getEventId()];
43 |     }
44 | 
45 |     public function getDataLayerArguments(): array
46 |     {
47 |         return [
48 |             'event' => 'conversionsApiPageView',
49 |             'conversionsApiPageViewEventId' => $this->getEventId()
50 |         ];
51 |     }
52 | }
53 | 


--------------------------------------------------------------------------------
/tests/Feature/View/Components/DataLayerVariableTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Tests\Support\Events\ContactEvent;
 7 | use Esign\ConversionsApi\Tests\TestCase;
 8 | use Esign\ConversionsApi\View\Components\DataLayerVariable;
 9 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
10 | 
11 | final class DataLayerVariableTest extends TestCase
12 | {
13 |     use InteractsWithViews;
14 | 
15 |     #[Test]
16 |     public function it_can_render_the_view(): void
17 |     {
18 |         $event = (new ContactEvent())->setEventId('9a97e3f0-3dbb-4d74-bf05-a42f330f843d');
19 |         $component = $this->component(DataLayerVariable::class, [
20 |             'event' => $event,
21 |         ]);
22 | 
23 |         $component->assertSee(
24 |             'window.dataLayer.push({"event":"Contact","conversionsApiContactEventId":"9a97e3f0-3dbb-4d74-bf05-a42f330f843d"});',
25 |             false
26 |         );
27 |     }
28 | 
29 |     #[Test]
30 |     public function it_can_render_anonymously(): void
31 |     {
32 |         $view = $this->blade('
33 |             <x-conversions-api::data-layer-variable
34 |                 :arguments="[\'event\' => \'contact\']"
35 |             />
36 |         ');
37 | 
38 |         $view->assertSee('window.dataLayer.push({"event":"contact"});', false);
39 |     }
40 | 
41 |     #[Test]
42 |     public function it_can_pass_component_attributes(): void
43 |     {
44 |         $view = $this->blade('
45 |             <x-conversions-api::data-layer-variable
46 |                 :arguments="[]"
47 |                 class="my-class"
48 |             />
49 |         ');
50 | 
51 |         $view->assertSee('<script class="my-class">', false);
52 |     }
53 | }
54 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "esign/laravel-conversions-api",
 3 |     "description": "A laravel wrapper package around the Facebook Conversions API",
 4 |     "keywords": [
 5 |         "esign",
 6 |         "conversions-api",
 7 |         "facebook"
 8 |     ],
 9 |     "homepage": "https://github.com/esign/laravel-conversions-api",
10 |     "license": "MIT",
11 |     "type": "library",
12 |     "authors": [
13 |         {
14 |             "name": "Jordy Van der Haegen",
15 |             "email": "jordy.vanderhaegen@gmail.com",
16 |             "role": "Developer"
17 |         }
18 |     ],
19 |     "require": {
20 |         "php": "^8.1",
21 |         "facebook/php-business-sdk": "^19.0",
22 |         "illuminate/http": "^10.0|^11.0|^12.0",
23 |         "illuminate/support": "^10.0|^11.0|^12.0"
24 |     },
25 |     "require-dev": {
26 |         "friendsofphp/php-cs-fixer": "^3.3",
27 |         "orchestra/testbench": "^8.0|^9.0|^10.0",
28 |         "phpunit/phpunit": "^10.1|^11.0"
29 |     },
30 |     "autoload": {
31 |         "psr-4": {
32 |             "Esign\\ConversionsApi\\": "src"
33 |         }
34 |     },
35 |     "autoload-dev": {
36 |         "psr-4": {
37 |             "Esign\\ConversionsApi\\Tests\\": "tests"
38 |         }
39 |     },
40 |     "scripts": {
41 |         "test": "vendor/bin/phpunit",
42 |         "phpcs": "vendor/bin/php-cs-fixer fix"
43 |     },
44 |     "config": {
45 |         "sort-packages": true
46 |     },
47 |     "extra": {
48 |         "laravel": {
49 |             "providers": [
50 |                 "Esign\\ConversionsApi\\ConversionsApiServiceProvider"
51 |             ],
52 |             "aliases": {
53 |                 "ConversionsApi": "Esign\\ConversionsApi\\Facades\\ConversionsApi"
54 |             }
55 |         }
56 |     },
57 |     "minimum-stability": "dev",
58 |     "prefer-stable": true
59 | }
60 | 


--------------------------------------------------------------------------------
/src/View/Components/FacebookPixelScript.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\View\Components;
 4 | 
 5 | use Esign\ConversionsApi\Facades\ConversionsApi;
 6 | use Illuminate\View\Component;
 7 | 
 8 | class FacebookPixelScript extends Component
 9 | {
10 |     protected ?string $pixelId;
11 |     protected array $advancedMatchingData;
12 | 
13 |     /**
14 |      * @param null|string $pixelId
15 |      * @param null|array $advancedMatchingData https://developers.facebook.com/docs/meta-pixel/advanced/advanced-matching#reference
16 |      * @return void
17 |      */
18 |     public function __construct(
19 |         ?string $pixelId = null,
20 |         ?array $advancedMatchingData = null
21 |     ) {
22 |         $this->pixelId = $pixelId ?? config('conversions-api.pixel_id');
23 |         $this->advancedMatchingData = $advancedMatchingData ?? $this->getAdvancedMatchingDataFromConversionsApiUserData();
24 |     }
25 | 
26 |     protected function getAdvancedMatchingDataFromConversionsApiUserData(): array
27 |     {
28 |         $userData = ConversionsApi::getUserData();
29 | 
30 |         return array_filter([
31 |             'em' => $userData->getEmail(),
32 |             'fn' => $userData->getFirstName(),
33 |             'ln' => $userData->getLastName(),
34 |             'ph' => $userData->getPhone(),
35 |             'external_id' => $userData->getExternalId(),
36 |             'ge' => $userData->getGender(),
37 |             'db' => $userData->getDateOfBirth(),
38 |             'ct' => $userData->getCity(),
39 |             'st' => $userData->getState(),
40 |             'zp' => $userData->getZipCode(),
41 |             'country' => $userData->getCountryCode(),
42 |         ]);
43 |     }
44 | 
45 |     public function render()
46 |     {
47 |         return view('conversions-api::components.facebook-pixel-script', [
48 |             'pixelId' => $this->pixelId,
49 |             'advancedMatchingData' => $this->advancedMatchingData,
50 |         ]);
51 |     }
52 | }
53 | 


--------------------------------------------------------------------------------
/UPGRADING.md:
--------------------------------------------------------------------------------
 1 | ## From v1 to v2
 2 | This package now supports to send multiple events at once to the Conversions API, instead of sending them one by one. While the previous version was mainly focused on sending `PageView` events, v2 now supports all kinds of events.
 3 | 
 4 | ### Method changes
 5 | - The `setEvent` method has been replaced by `addEvent`, `addEvents` and `setEvents` methods.
 6 | - The `getEvent` method has been removed in favor of `getEvents`.
 7 | - The `execute` method has been replaced by `sendEvents`.
 8 | - The `setEventByName` method has been removed, it's recommended to create [dedicated event classes](README.MD#creating-event-classes) for this.
 9 | - The `executePageViewEvent` has been removed and is now handled in dedicated view components, see [PageView Events](README.md#pageview-events)
10 | - The `getEventId` and `setEventId` methods have been removed, since this package now supports multiple events, that each have their own unique event id.
11 | You may use Laravel's built-in `Str::uuid()` helper to create unique event id's.
12 | See the [docs](README.md#creating-event-classes) for an example on this.
13 | 
14 | ### Directive changes
15 | - The `@conversionsApiPageView` directive has been replaced by 2 view components, depending on your deduplication preference.
16 | In case you're using the Facebook Pixel directly, use `<x-conversions-api-facebook-pixel-page-view />`.
17 | If you're sending them through Google Tag Manager, use `<x-conversions-api-data-layer-page-view />`.
18 | Note that the dataLayer variable name has been changed from `conversionsApiEventId` to `conversionsApiPageViewEventId`.
19 | - The `@conversionsApiFacebookPixelScript` directive has been replaced with `<x-conversions-api-facebook-pixel-script />`.
20 | - The `@conversionsApiDataLayer` has been removed. Support for dataLayer events is possible through `<x-conversions-api-data-layer-variable :event="$event" />` or `<x-conversions-api::data-layer-variable :arguments="[]" />`. See the [docs](README.md#google-tag-manager) for an example on this.


--------------------------------------------------------------------------------
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
 1 | name: run-tests
 2 | 
 3 | on:
 4 |     push:
 5 |         branches: [master]
 6 |     pull_request:
 7 |         branches: [master]
 8 | 
 9 | jobs:
10 |     test:
11 |         runs-on: ${{ matrix.os }}
12 |         strategy:
13 |             fail-fast: true
14 |             matrix:
15 |                 os: [ubuntu-latest]
16 |                 php: [8.5, 8.4, 8.3, 8.2, 8.1]
17 |                 laravel: [12.*, 11.*, 10.*]
18 |                 stability: [prefer-lowest, prefer-stable]
19 |                 include:
20 |                     - laravel: 12.*
21 |                       testbench: 10.*
22 |                     - laravel: 11.*
23 |                       testbench: ^9.9
24 |                     - laravel: 10.*
25 |                       testbench: 8.*
26 |                 exclude:
27 |                     - laravel: 12.*
28 |                       php: 8.1
29 |                     - laravel: 11.*
30 |                       php: 8.1
31 | 
32 |         name: P${{ matrix.php }} - L${{ matrix.laravel }} - ${{ matrix.stability }} - ${{ matrix.os }}
33 | 
34 |         steps:
35 |             - name: Checkout code
36 |               uses: actions/checkout@v4
37 | 
38 |             - name: Setup PHP
39 |               uses: shivammathur/setup-php@v2
40 |               with:
41 |                   php-version: ${{ matrix.php }}
42 |                   extensions: dom, curl, libxml, mbstring, zip, pcntl, pdo, sqlite, pdo_sqlite, bcmath, soap, intl, gd, exif, iconv, imagick, fileinfo
43 |                   coverage: none
44 | 
45 |             - name: Setup problem matchers
46 |               run: |
47 |                   echo "::add-matcher::${{ runner.tool_cache }}/php.json"
48 |                   echo "::add-matcher::${{ runner.tool_cache }}/phpunit.json"
49 |             - name: Install dependencies
50 |               run: |
51 |                   composer require "laravel/framework:${{ matrix.laravel }}" "orchestra/testbench:${{ matrix.testbench }}" --no-interaction --no-update
52 |                   composer update --${{ matrix.stability }} --prefer-dist --no-interaction
53 |             - name: Execute tests
54 |               run: vendor/bin/phpunit
55 | 


--------------------------------------------------------------------------------
/src/ConversionsApi.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi;
 4 | 
 5 | use Esign\ConversionsApi\Collections\EventCollection;
 6 | use Esign\ConversionsApi\Objects\DefaultUserData;
 7 | use FacebookAds\Api;
 8 | use FacebookAds\Object\ServerSide\Event;
 9 | use FacebookAds\Object\ServerSide\EventRequestAsync;
10 | use FacebookAds\Object\ServerSide\UserData;
11 | use GuzzleHttp\Promise\PromiseInterface;
12 | 
13 | class ConversionsApi
14 | {
15 |     protected EventCollection $events;
16 |     protected UserData $userData;
17 | 
18 |     public function __construct()
19 |     {
20 |         $this->events = new EventCollection();
21 |         $this->setUserData(DefaultUserData::create());
22 |         Api::init(null, null, config('conversions-api.access_token'), false);
23 |     }
24 | 
25 |     public function setUserData(UserData $userData): self
26 |     {
27 |         $this->userData = $userData;
28 | 
29 |         return $this;
30 |     }
31 | 
32 |     public function getUserData(): UserData
33 |     {
34 |         return $this->userData;
35 |     }
36 | 
37 |     public function addEvent(Event $event): self
38 |     {
39 |         $this->events->push($event);
40 | 
41 |         return $this;
42 |     }
43 | 
44 |     public function addEvents(iterable $events): self
45 |     {
46 |         $this->events = $this->events->merge($events);
47 | 
48 |         return $this;
49 |     }
50 | 
51 |     public function setEvents(iterable $events): self
52 |     {
53 |         $this->events = new EventCollection($events);
54 | 
55 |         return $this;
56 |     }
57 | 
58 |     public function getEvents(): EventCollection
59 |     {
60 |         return $this->events;
61 |     }
62 | 
63 |     public function clearEvents(): self
64 |     {
65 |         return $this->setEvents([]);
66 |     }
67 | 
68 |     public function sendEvents(): PromiseInterface
69 |     {
70 |         $eventRequest = (new EventRequestAsync(config('conversions-api.pixel_id')))
71 |             ->setEvents($this->events);
72 | 
73 |         if ($testCode = config('conversions-api.test_code')) {
74 |             $eventRequest->setTestEventCode($testCode);
75 |         }
76 | 
77 |         return $eventRequest->execute();
78 |     }
79 | }
80 | 


--------------------------------------------------------------------------------
/tests/Feature/View/Components/FacebookPixelScriptTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Facades\ConversionsApi;
 7 | use Esign\ConversionsApi\Tests\TestCase;
 8 | use Esign\ConversionsApi\View\Components\FacebookPixelScript;
 9 | use FacebookAds\Object\ServerSide\UserData;
10 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
11 | use Illuminate\Support\Facades\Config;
12 | 
13 | final class FacebookPixelScriptTest extends TestCase
14 | {
15 |     use InteractsWithViews;
16 | 
17 |     #[Test]
18 |     public function it_can_render_the_view_using_default_data(): void
19 |     {
20 |         Config::set('conversions-api.pixel_id', '414800860114807');
21 |         ConversionsApi::setUserData((new UserData())->setEmail('test@test.com'));
22 |         $component = $this->component(FacebookPixelScript::class);
23 | 
24 |         $component->assertSee("fbq('init', '414800860114807', {\"em\":\"test@test.com\"});", false);
25 |     }
26 | 
27 |     #[Test]
28 |     public function it_can_render_an_empty_object_for_advanced_matching_data(): void
29 |     {
30 |         Config::set('conversions-api.pixel_id', '414800860114807');
31 |         $component = $this->component(FacebookPixelScript::class);
32 | 
33 |         $component->assertSee("fbq('init', '414800860114807', {});", false);
34 |     }
35 | 
36 |     #[Test]
37 |     public function it_can_render_the_view_passing_custom_data(): void
38 |     {
39 |         $component = $this->component(FacebookPixelScript::class, [
40 |             'pixelId' => '744689831385767',
41 |             'advancedMatchingData' => ['em' => 'test@test.com'],
42 |         ]);
43 | 
44 |         $component->assertSee("fbq('init', '744689831385767', {\"em\":\"test@test.com\"});", false);
45 |     }
46 | 
47 |     #[Test]
48 |     public function it_can_pass_component_attributes(): void
49 |     {
50 |         $view = $this->blade('
51 |             <x-conversions-api::data-layer-variable
52 |                 :arguments="[]"
53 |                 class="my-class"
54 |             />
55 |         ');
56 | 
57 |         $view->assertSee('<script class="my-class">', false);
58 |     }
59 | }
60 | 


--------------------------------------------------------------------------------
/src/ConversionsApiServiceProvider.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi;
 4 | 
 5 | use Esign\ConversionsApi\Facades\ConversionsApi;
 6 | use Esign\ConversionsApi\View\Components\DataLayerPageView;
 7 | use Esign\ConversionsApi\View\Components\DataLayerUserDataVariable;
 8 | use Esign\ConversionsApi\View\Components\DataLayerVariable;
 9 | use Esign\ConversionsApi\View\Components\FacebookPixelPageView;
10 | use Esign\ConversionsApi\View\Components\FacebookPixelScript;
11 | use Esign\ConversionsApi\View\Components\FacebookPixelTrackingEvent;
12 | use Esign\ConversionsApi\View\Components\GoogleTagManagerBody;
13 | use Esign\ConversionsApi\View\Components\GoogleTagManagerHead;
14 | use Illuminate\Support\ServiceProvider;
15 | 
16 | class ConversionsApiServiceProvider extends ServiceProvider
17 | {
18 |     public function boot()
19 |     {
20 |         $this->loadViewsFrom($this->viewPath(), 'conversions-api');
21 |         $this->loadViewComponentsAs('conversions-api', [
22 |             'data-layer-page-view' => DataLayerPageView::class,
23 |             'data-layer-variable' => DataLayerVariable::class,
24 |             'data-layer-user-variable' => DataLayerUserDataVariable::class,
25 |             'facebook-pixel-script' => FacebookPixelScript::class,
26 |             'facebook-pixel-page-view' => FacebookPixelPageView::class,
27 |             'facebook-pixel-tracking-event' => FacebookPixelTrackingEvent::class,
28 |             'google-tag-manager-body' => GoogleTagManagerBody::class,
29 |             'google-tag-manager-head' => GoogleTagManagerHead::class,
30 |         ]);
31 | 
32 |         if ($this->app->runningInConsole()) {
33 |             $this->publishes([$this->configPath() => config_path('conversions-api.php')], 'config');
34 |             $this->publishes([$this->viewPath() => resource_path('views/vendor/conversions-api')], 'views');
35 |         }
36 |     }
37 | 
38 |     public function register()
39 |     {
40 |         $this->mergeConfigFrom($this->configPath(), 'conversions-api');
41 |         $this->app->singleton(ConversionsApi::class);
42 |     }
43 | 
44 |     protected function configPath(): string
45 |     {
46 |         return __DIR__ . '/../config/conversions-api.php';
47 |     }
48 | 
49 |     protected function viewPath(): string
50 |     {
51 |         return __DIR__ . '/../resources/views';
52 |     }
53 | }
54 | 


--------------------------------------------------------------------------------
/tests/Feature/View/Components/FacebookPixelTrackingEventTest.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | namespace Esign\ConversionsApi\Tests\Feature\View\Components;
 4 | 
 5 | use PHPUnit\Framework\Attributes\Test;
 6 | use Esign\ConversionsApi\Tests\Support\Events\PurchaseEvent;
 7 | use Esign\ConversionsApi\Tests\TestCase;
 8 | use Esign\ConversionsApi\View\Components\FacebookPixelTrackingEvent;
 9 | use FacebookAds\Object\ServerSide\Content;
10 | use FacebookAds\Object\ServerSide\CustomData;
11 | use Illuminate\Foundation\Testing\Concerns\InteractsWithViews;
12 | 
13 | final class FacebookPixelTrackingEventTest extends TestCase
14 | {
15 |     use InteractsWithViews;
16 | 
17 |     #[Test]
18 |     public function it_can_render_the_view(): void
19 |     {
20 |         $event = (new PurchaseEvent());
21 |         $component = $this->component(FacebookPixelTrackingEvent::class, [
22 |             'event' => $event,
23 |         ]);
24 | 
25 |         $component->assertSee('track');
26 |         $component->assertSee('Purchase');
27 |     }
28 | 
29 |     #[Test]
30 |     public function it_can_encode_custom_data_and_event_data_as_objects_when_they_are_empty_arrays(): void
31 |     {
32 |         $event = (new PurchaseEvent());
33 |         $component = $this->component(FacebookPixelTrackingEvent::class, [
34 |             'event' => $event,
35 |         ]);
36 | 
37 |         $component->assertSee(
38 |             "fbq('track', 'Purchase', {}, {});",
39 |             false
40 |         );
41 |     }
42 | 
43 |     #[Test]
44 |     public function it_can_json_encode_custom_data_and_event_data(): void
45 |     {
46 |         $contents = (new Content())->setProductId('10')->setQuantity(2);
47 |         $customData = (new CustomData())->setValue(120)->setCurrency('GBP')->setContents([$contents]);
48 |         $event = (new PurchaseEvent())->setCustomData($customData)->setEventId('123');
49 |         $component = $this->component(FacebookPixelTrackingEvent::class, [
50 |             'event' => $event,
51 |         ]);
52 | 
53 |         $component->assertSee(
54 |             "fbq('track', 'Purchase', {\"value\":120,\"currency\":\"GBP\",\"contents\":[{\"id\":\"10\",\"quantity\":2}]}, {\"eventID\":\"123\"});",
55 |             false
56 |         );
57 |     }
58 | 
59 |     #[Test]
60 |     public function it_can_render_anonymously(): void
61 |     {
62 |         $view = $this->blade('
63 |             <x-conversions-api::facebook-pixel-tracking-event
64 |                 eventType="track"
65 |                 eventName="Purchase"
66 |                 :customData="[]"
67 |                 :eventData="[]"
68 |             />
69 |         ');
70 | 
71 |         $view->assertSee("fbq('track', 'Purchase', {}, {});", false);
72 |     }
73 | 
74 |     #[Test]
75 |     public function it_can_pass_component_attributes(): void
76 |     {
77 |         $view = $this->blade('
78 |             <x-conversions-api::facebook-pixel-tracking-event
79 |                 eventType="track"
80 |                 eventName="Purchase"
81 |                 :customData="[]"
82 |                 :eventData="[]"
83 |                 class="my-class"
84 |             />
85 |         ');
86 | 
87 |         $view->assertSee('<script class="my-class">', false);
88 |     }
89 | }
90 | 


--------------------------------------------------------------------------------
/tests/Feature/ConversionsApiTest.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | namespace Esign\ConversionsApi\Tests\Feature;
  4 | 
  5 | use PHPUnit\Framework\Attributes\Test;
  6 | use Esign\ConversionsApi\Collections\EventCollection;
  7 | use Esign\ConversionsApi\Facades\ConversionsApi;
  8 | use Esign\ConversionsApi\Tests\TestCase;
  9 | use FacebookAds\Object\ServerSide\Event;
 10 | use FacebookAds\Object\ServerSide\UserData;
 11 | 
 12 | final class ConversionsApiTest extends TestCase
 13 | {
 14 |     #[Test]
 15 |     public function it_can_set_user_data_by_default(): void
 16 |     {
 17 |         request()->headers->set('USER_AGENT', 'Esign Agent');
 18 |         request()->server->set('REMOTE_ADDR', '0.0.0.0');
 19 | 
 20 |         $this->assertEquals('0.0.0.0', ConversionsApi::getUserData()->getClientIpAddress());
 21 |         $this->assertEquals('Esign Agent', ConversionsApi::getUserData()->getClientUserAgent());
 22 |     }
 23 | 
 24 |     #[Test]
 25 |     public function it_can_set_user_data(): void
 26 |     {
 27 |         ConversionsApi::setUserData(
 28 |             (new UserData())->setFirstName('John')->setLastName('Doe')
 29 |         );
 30 | 
 31 |         $this->assertEquals('John', ConversionsApi::getUserData()->getFirstName());
 32 |         $this->assertEquals('Doe', ConversionsApi::getUserData()->getLastName());
 33 |     }
 34 | 
 35 |     #[Test]
 36 |     public function it_can_add_an_event(): void
 37 |     {
 38 |         ConversionsApi::addEvent(
 39 |             (new Event())->setEventName('PageView')->setEventId('abc')
 40 |         );
 41 | 
 42 |         $this->assertCount(1, ConversionsApi::getEvents());
 43 |         $this->assertEquals('PageView', ConversionsApi::getEvents()->first()->getEventName());
 44 |         $this->assertEquals('abc', ConversionsApi::getEvents()->first()->getEventId());
 45 |     }
 46 | 
 47 |     #[Test]
 48 |     public function it_can_add_multiple_events(): void
 49 |     {
 50 |         ConversionsApi::addEvent(
 51 |             (new Event())->setEventName('PageView')->setEventId('abc')
 52 |         );
 53 |         ConversionsApi::addEvents([
 54 |             (new Event())->setEventName('PageView')->setEventId('xyz'),
 55 |         ]);
 56 | 
 57 |         $this->assertCount(2, ConversionsApi::getEvents());
 58 |         $this->assertEquals('PageView', ConversionsApi::getEvents()->first()->getEventName());
 59 |         $this->assertEquals('abc', ConversionsApi::getEvents()->first()->getEventId());
 60 |     }
 61 | 
 62 |     #[Test]
 63 |     public function it_can_set_an_array_of_events(): void
 64 |     {
 65 |         ConversionsApi::addEvent(
 66 |             (new Event())->setEventName('PageView')->setEventId('abc')
 67 |         );
 68 |         ConversionsApi::setEvents([
 69 |             (new Event())->setEventName('PageView')->setEventId('xyz'),
 70 |         ]);
 71 | 
 72 |         $this->assertCount(1, ConversionsApi::getEvents());
 73 |         $this->assertEquals('PageView', ConversionsApi::getEvents()->first()->getEventName());
 74 |         $this->assertEquals('xyz', ConversionsApi::getEvents()->first()->getEventId());
 75 |     }
 76 | 
 77 |     #[Test]
 78 |     public function it_can_clear_events(): void
 79 |     {
 80 |         ConversionsApi::setEvents([
 81 |             (new Event())->setEventName('PageView')->setEventId('abc'),
 82 |         ]);
 83 | 
 84 |         ConversionsApi::clearEvents();
 85 | 
 86 |         $this->assertCount(0, ConversionsApi::getEvents());
 87 |     }
 88 | 
 89 |     #[Test]
 90 |     public function it_can_get_events(): void
 91 |     {
 92 |         ConversionsApi::setEvents([
 93 |             (new Event())->setEventName('PageView')->setEventId('abc'),
 94 |         ]);
 95 | 
 96 |         $events = ConversionsApi::getEvents();
 97 | 
 98 |         $this->assertInstanceOf(EventCollection::class, $events);
 99 |         $this->assertCount(1, $events);
100 |     }
101 | }
102 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Interact with the Facebook Conversions API
  2 | 
  3 | [![Latest Version on Packagist](https://img.shields.io/packagist/v/esign/laravel-conversions-api.svg?style=flat-square)](https://packagist.org/packages/esign/laravel-conversions-api)
  4 | [![Total Downloads](https://img.shields.io/packagist/dt/esign/laravel-conversions-api.svg?style=flat-square)](https://packagist.org/packages/esign/laravel-conversions-api)
  5 | ![GitHub Actions](https://github.com/esign/laravel-conversions-api/actions/workflows/main.yml/badge.svg)
  6 | 
  7 | This package allow you to easily interact with the [Facebook Conversions API](https://developers.facebook.com/docs/marketing-api/conversions-api/).
  8 | 
  9 | ## Installation
 10 | 
 11 | You can install the package via composer:
 12 | 
 13 | ```bash
 14 | composer require esign/laravel-conversions-api
 15 | ```
 16 | 
 17 | Next up, you can publish the configuration file:
 18 | ```bash
 19 | php artisan vendor:publish --provider="Esign\ConversionsApi\ConversionsApiServiceProvider" --tag="config"
 20 | ```
 21 | 
 22 | The config file will be published as config/conversions-api.php with the following content:
 23 | ```php
 24 | return [
 25 |     /**
 26 |      * The access token used by the Conversions API.
 27 |      */
 28 |     'access_token' => env('CONVERSIONS_API_ACCESS_TOKEN'),
 29 | 
 30 |     /**
 31 |      * The pixel ID used by the Conversions API.
 32 |      */
 33 |     'pixel_id' => env('CONVERSIONS_API_PIXEL_ID'),
 34 | 
 35 |     /**
 36 |      * The Google Tag Manager container ID used in case you're deduplicating
 37 |      * events through Google Tag Manager instead of Facebook Pixel directly.
 38 |      * Should look something like "GTM-XXXXXX".
 39 |      */
 40 |     'gtm_id' => env('GOOGLE_TAG_MANAGER_ID'),
 41 | 
 42 |     /**
 43 |      * The Conversions API comes with a nice way to test your events.
 44 |      * You may use this config variable to set your test code.
 45 |      */
 46 |     'test_code' => env('CONVERSIONS_API_TEST_CODE'),
 47 | ];
 48 | ```
 49 | 
 50 | In case you want to customize the view components you may also publish the views:
 51 | ```bash
 52 | php artisan vendor:publish --provider="Esign\ConversionsApi\ConversionsApiServiceProvider" --tag="views"
 53 | ```
 54 | 
 55 | ## Conversions API
 56 | 
 57 | ### Events
 58 | To add events to the conversions API you may use the `addEvent`, `addEvents` or `setEvents` methods.
 59 | Retrieving or clearing events may be done using the `getEvents` and `clearEvents` methods:
 60 | ```php
 61 | use Esign\ConversionsApi\Facades\ConversionsApi;
 62 | use FacebookAds\Object\ServerSide\UserData;
 63 | use FacebookAds\Object\ServerSide\Event;
 64 | 
 65 | ConversionsApi::addEvent(
 66 |     (new Event())->setEventName('PageView')->setEventId('abc')
 67 | );
 68 | 
 69 | ConversionsApi::setEvents([
 70 |     (new Event())->setEventName('PageView')->setEventId('abc'),
 71 |     (new Event())->setEventName('Purchase')->setEventId('xyz'),
 72 | ]);
 73 | 
 74 | ConversionsApi::getEvents();
 75 | ConversionsApi::clearEvents();
 76 | ```
 77 | 
 78 | Adding events won't cause them to be sent to the Conversions API.
 79 | To actually send the events you must call the `sendEvents` method:
 80 | ```php
 81 | use Esign\ConversionsApi\Facades\ConversionsApi;
 82 | 
 83 | ConversionsApi::sendEvents();
 84 | ```
 85 | 
 86 | #### Creating event classes
 87 | To make things a bit cleaner you may extend Facebook's default event class:
 88 | 
 89 | ```php
 90 | use Esign\ConversionsApi\Facades\ConversionsApi;
 91 | use FacebookAds\Object\ServerSide\ActionSource;
 92 | use FacebookAds\Object\ServerSide\Event;
 93 | 
 94 | class PurchaseEvent extends Event
 95 | {
 96 |     public static function create(): static
 97 |     {
 98 |         return (new static())
 99 |             ->setActionSource(ActionSource::WEBSITE)
100 |             ->setEventName('Purchase')
101 |             ->setEventTime(time())
102 |             ->setEventSourceUrl(request()->fullUrl())
103 |             ->setEventId((string) Str::uuid())
104 |             ->setUserData(ConversionsApi::getUserData());
105 |     }
106 | }
107 | ```
108 | ```php
109 | ConversionsApi::addEvent(
110 |     PurchaseEvent::create()
111 | );
112 | ```
113 | 
114 | ### User Data
115 | This package also comes with a way to define default user data for the user of the current request.
116 | You may do so by calling the `setUserData` method.
117 | You can set the user data for every incoming request by creating a custom middleware like this one:
118 | 
119 | ```php
120 | namespace App\Http\Middleware;
121 | 
122 | use Esign\ConversionsApi\Facades\ConversionsApi;
123 | use Esign\ConversionsApi\Objects\DefaultUserData;
124 | 
125 | class InitializeFacebookUserData
126 | {
127 |     public function handle(Request $request, Closure $next): Response
128 |     {
129 |         ConversionsApi::setUserData(
130 |             DefaultUserData::create()
131 |                 ->setEmail($request->user()?->email)
132 |         );
133 | 
134 |         return $next($request);
135 |     }
136 | }
137 | 
138 | ```
139 | 
140 | You can now use it in `App\Http\Kernel` as a global middleware or a route middleware.
141 | 
142 | You may now pass the user data along with your events:
143 | ```php
144 | use Esign\ConversionsApi\Facades\ConversionsApi;
145 | use FacebookAds\Object\ServerSide\Event;
146 | 
147 | ConversionsApi::addEvent(
148 |     (new Event())->setUserData(ConversionsApi::getUserData())
149 | );
150 | ```
151 | 
152 | ## Event deduplication
153 | This package comes with a few ways to assist you in [deduplicating browser and server events](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events/). This can either be done using the Facebook Pixel directly or through Google Tag Manager's data layer.
154 | 
155 | ### Facebook Pixel
156 | Before attempting to send events through Facebook Pixel make sure to load the pixel script:
157 | ```blade
158 | <x-conversions-api-facebook-pixel-script />
159 | ```
160 | 
161 | This will render the following html:
162 | ```html
163 | <script>
164 |     !function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
165 |     n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
166 |     n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
167 |     t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
168 |     document,'script','https://connect.facebook.net/en_US/fbevents.js');
169 | 
170 |     fbq('init', 'your-configured-pixel-id', {});
171 | </script>
172 | ```
173 | 
174 | This package will attempt to provide as much advanced matching data as possible by using user data from the `ConversionsApi`.
175 | For example when an email address is set, it will automatically be provided to the init method:
176 | ```php
177 | ConversionsApi::setUserData(
178 |     (new UserData())->setEmail('john@example.com')
179 | );
180 | ```
181 | ```js
182 | fbq('init', 'your-configured-pixel-id', {"em": "john@example.com"});
183 | ```
184 | 
185 | Now that your Pixel is correctly initialized, it's time to send some events.
186 | Sadly the parameters between the Conversions API and Facebook Pixel are not identical, so they must be mapped to the [correct format](https://developers.facebook.com/docs/meta-pixel/reference).
187 | An easy way of doing this is by extending the `FacebookAds\Object\ServerSide\Event` class and implementing the `Esign\ConversionsApi\Contracts\MapsToFacebookPixel` interface on it:
188 | ```php
189 | use Esign\ConversionsApi\Contracts\MapsToFacebookPixel;
190 | use Esign\ConversionsApi\Facades\ConversionsApi;
191 | use FacebookAds\Object\ServerSide\ActionSource;
192 | use FacebookAds\Object\ServerSide\Event;
193 | 
194 | class PurchaseEvent extends Event implements MapsToFacebookPixel
195 | {
196 |     public static function create(): static
197 |     {
198 |         return (new static())
199 |             ->setActionSource(ActionSource::WEBSITE)
200 |             ->setEventName('Purchase')
201 |             ->setEventTime(time())
202 |             ->setEventSourceUrl(request()->fullUrl())
203 |             ->setEventId((string) Str::uuid())
204 |             ->setUserData(ConversionsApi::getUserData());
205 |     }
206 | 
207 |     public function getFacebookPixelEventType(): string
208 |     {
209 |         return 'track';
210 |     }
211 | 
212 |     public function getFacebookPixelEventName(): string
213 |     {
214 |         return $this->getEventName();
215 |     }
216 | 
217 |     public function getFacebookPixelCustomData(): array
218 |     {
219 |         $customData = $this->getCustomData();
220 | 
221 |         return array_filter([
222 |             'currency' => $customData?->getCurrency(),
223 |             'value' => $customData?->getValue(),
224 |         ]);
225 |     }
226 | 
227 |     public function getFacebookPixelEventData(): array
228 |     {
229 |         return array_filter(['eventID' => $this->getEventId()]);
230 |     }
231 | }
232 | ```
233 | 
234 | You may now pass any class that implements the `MapsToFacebookPixel` interface to the view component responsible for tracking Facebook Pixel events:
235 | ```php
236 | use FacebookAds\Object\ServerSide\CustomData;
237 | use Illuminate\Support\Str;
238 | 
239 | $event = PurchaseEvent::create()->setCustomData(
240 |     (new CustomData())->setCurrency('EUR')->setValue(10)
241 | );
242 | ```
243 | 
244 | ```blade
245 | <x-conversions-api-facebook-pixel-tracking-event :event="$event" />
246 | ```
247 | 
248 | This will render the following script tag:
249 | ```html
250 | <script>
251 |     fbq('track', 'Purchase', {"currency": "EUR", "value": 10}, {"eventID": "ccf928e1-56fd-4376-bee3-dda0d7dbe136"});
252 | </script>
253 | ```
254 | 
255 | To retrieve a list of all events that implement the `MapsToFacebookPixel` interface you may call the `filterFacebookPixelEvents` method:
256 | ```blade
257 | @foreach(ConversionsApi::getEvents()->filterFacebookPixelEvents() as $event)
258 |     <x-conversions-api-facebook-pixel-tracking-event :event="$event" />
259 | @endforeach
260 | ```
261 | 
262 | In case you want more control over what's being rendered, you may always use the anonymous component:
263 | ```blade
264 | <x-conversions-api::facebook-pixel-tracking-event
265 |     eventType="track"
266 |     eventName="Purchase"
267 |     :customData="[]"
268 |     :eventData="[]"
269 | />
270 | ```
271 | 
272 | ### Google Tag Manager
273 | Before attempting to deduplicate events through GTM make sure to configure your GTM container id and include the necessary scripts:
274 | 
275 | ```env
276 | GOOGLE_TAG_MANAGER_ID=GTM-XXXXXX
277 | ```
278 | 
279 | ```blade
280 | <html>
281 |   <head>
282 |     <x-conversions-api-google-tag-manager-head />
283 |     {{-- ... --}}
284 |   </head>
285 |   <body>
286 |     <x-conversions-api-google-tag-manager-body />
287 |     {{-- ... --}}
288 |   </body>
289 | </html>
290 | ```
291 | 
292 | This package comes with a view component that will map all user data from the `ConversionsApi` to dataLayer variables:
293 | ```blade
294 | <x-conversions-api-data-layer-user-variable />
295 | ```
296 | For example when an email address is set, it will be automatically mapped to a dataLayer variable.
297 | Check the [source](src/View/Components/DataLayerUserDataVariable.php) of the view component to see a list of all possible variables.
298 | ```php
299 | ConversionsApi::setUserData(
300 |     (new UserData())->setEmail('john@example.com')
301 | );
302 | ```
303 | ```js
304 | window.dataLayer.push({"conversionsApiUserEmail": "john@example.com"});
305 | ```
306 | 
307 | Now that your Pixel through GTM is correctly initialized, it's time to send some events.
308 | An easy way of doing this is by extending the `FacebookAds\Object\ServerSide\Event` class and implementing the `Esign\ConversionsApi\Contracts\MapsToDataLayer` interface on it:
309 | ```php
310 | use Esign\ConversionsApi\Contracts\MapsToDataLayer;
311 | use Esign\ConversionsApi\Facades\ConversionsApi;
312 | use FacebookAds\Object\ServerSide\ActionSource;
313 | use FacebookAds\Object\ServerSide\Event;
314 | 
315 | class PurchaseEvent extends Event implements MapsToDataLayer
316 | {
317 |     public static function create(): static
318 |     {
319 |         return (new static())
320 |             ->setActionSource(ActionSource::WEBSITE)
321 |             ->setEventName('Purchase')
322 |             ->setEventTime(time())
323 |             ->setEventSourceUrl(request()->fullUrl())
324 |             ->setEventId((string) Str::uuid())
325 |             ->setUserData(ConversionsApi::getUserData());
326 |     }
327 | 
328 |     public function getDataLayerArguments(): array
329 |     {
330 |         $customData = $this->getCustomData();
331 | 
332 |         return [
333 |             'event' => 'conversionsApiPurchase',
334 |             'conversionsApiPurchaseEventId' => $this->getEventId(),
335 |             'conversionsApiPurchaseCurrency' => $customData?->getCurrency(),
336 |             'conversionsApiPurchaseValue' => $customData?->getValue(),
337 |         ];
338 |     }
339 | }
340 | ```
341 | 
342 | You may now pass any class that implements the `MapsToDataLayer` interface to the view component responsible for tracking Facebook Pixel events:
343 | ```php
344 | use FacebookAds\Object\ServerSide\CustomData;
345 | use Illuminate\Support\Str;
346 | 
347 | $event = PurchaseEvent::create()->setCustomData(
348 |     (new CustomData())->setCurrency('EUR')->setValue(10)
349 | );
350 | ```
351 | 
352 | ```blade
353 | <x-conversions-api-data-layer-variable :event="$event" />
354 | ```
355 | 
356 | This will render the following script tag:
357 | ```html
358 | <script>
359 |     window.dataLayer.push({
360 |         "event": "conversionsApiPurchase",
361 |         "conversionsApiPurchaseEventId": "e2481afc-5af4-4483-bc4b-33f08e195e3a",
362 |         "conversionsApiPurchaseCurrency": "EUR",
363 |         "conversionsApiPurchaseValue": 120
364 |     });
365 | </script>
366 | ```
367 | 
368 | To retrieve a list of all events that implement the `MapsToDataLayer` interface you may call the `filterDataLayerEvents` method:
369 | ```blade
370 | @foreach(ConversionsApi::getEvents()->filterDataLayerEvents() as $event)
371 |     <x-conversions-api-data-layer-variable :event="$event" />
372 | @endforeach
373 | ```
374 | 
375 | In case you want more control over what's being rendered, you may always use the anonymous component:
376 | ```blade
377 | <x-conversions-api::data-layer-variable :arguments="[]" />
378 | ```
379 | 
380 | ## PageView Events
381 | This package ships with some helpers to track `PageView` events out of the box.
382 | These helpers will automatically send both Conversions API & Facebook Pixel events and provide event deduplication.
383 | > **Note**
384 | > Make sure to always include these view components after you've already looped over any other events currently defined on the ConversionsApi. Including these view components will clear any existing events.
385 | 
386 | In case you're using the Facebook Pixel directly:
387 | ```blade
388 | <x-conversions-api-facebook-pixel-page-view />
389 | ```
390 | Or by using Google Tag Manager. The data-layer variable to deduplicate events is called `conversionsApiPageViewEventId`.
391 | ```blade
392 | <x-conversions-api-data-layer-page-view />
393 | ```
394 | 
395 | ## Troubleshooting
396 | ### PageView events are not shown as deduplicated in the test events dashboard
397 | Event deduplication for PageView events should be fine out of the box, since the event name and event id parameters have been provided.
398 | However, when serving your application locally the ip address returned by Laravel's `request()->ip()` will be `127.0.0.1`.
399 | This is different from the ip address sent through Facebook Pixel, causing the Conversions API and Facebook Pixel events to not be deduplicated.
400 | This issue should solve itself once the application will be ran in production.
401 | 
402 | ### Whitelisting Cookies in Laravel
403 | When using ``\App\Http\Middleware\EncryptCookies::class`` in ``\App\Http\Kernel::class``, ensure to whitelist _fbp and _fbc cookies to prevent null values in loading ``DefaultUserData::create()``. Update the $except property in the EncryptCookies middleware as shown below:
404 | 
405 | ```php
406 | <?php
407 | 
408 | namespace App\Http\Middleware;
409 | 
410 | use Illuminate\Cookie\Middleware\EncryptCookies as Middleware;
411 | 
412 | class EncryptCookies extends Middleware
413 | {
414 |     /**
415 |      * The names of the cookies that should not be encrypted.
416 |      *
417 |      * @var array
418 |      */
419 |     protected $except = [
420 |         '_fbp',
421 |         '_fbc'
422 |     ];
423 | }
424 | ```
425 | 
426 | ## Testing
427 | 
428 | ```bash
429 | composer test
430 | ```
431 | 
432 | ## License
433 | 
434 | The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
435 | 


--------------------------------------------------------------------------------