README

为您的 Laravel 应用程序提供完整的 Meta Pixel 实现。

关于 Combind Agency

Combine Agency 是一家领先的网页开发公司，专注于使用现代技术构建创新和高性能的网页应用程序。我们经验丰富的开发人员、设计师和项目经理致力于为客户提供定制化服务，满足客户的独特需求。

如果您需要帮助您的下一个项目或想讨论定制解决方案，请随时联系我们或访问我们的网站了解更多关于我们服务的信息。让我们一起创造一些令人惊叹的东西吧！

简介

此包提供了 Meta Pixel 的顺畅集成，以及最新的 Conversions API 的简单实现，提升了您的整体体验。

版本 4.0 的文档 - 旧版本

升级到版本 5

如果您从版本 4 升级，请参阅我们的版本 5 迁移指南，了解如何进行平稳过渡的详细说明。

先决条件

注册 Meta Pixel

要开始使用 Meta pixel，您必须注册一个像素：阅读此指南。

Conversions API

如果您计划使用 Conversions API，则需要

获取访问令牌

要使用 Conversions API，您需要生成一个访问令牌，该令牌将作为每个 API 调用的参数传递。

请参阅 Conversions API 指南了解更多信息。

安装

您可以通过 composer 安装此包

composer require combindma/laravel-facebook-pixel

可选地，您可以使用以下命令发布视图

php artisan vendor:publish --tag="meta-pixel-views"

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="meta-pixel-config"

这是已发布的配置文件的内容

return [
   /*
     * The Meta pixel id, should be a code that looks something like "1202417153106158".
     */
    'pixel_id' => env('META_PIXEL_ID', ''),

    /*
     * The key under which data is saved to the session with flash.
     */
    'session_key' => env('META_PIXEL_SESSION_KEY', config('app.name').'_metaPixel'),

    /*
     * Only if you plan using Conversions API for server events
     * To use the Conversions API, you need an access token. For Documentation please see: https://developers.facebook.com/docs/marketing-api/conversions-api/get-started
     */
    'token' => env('META_PIXEL_TOKEN', ''),

    /*
     * Enable or disable advanced matching. Useful for adjusting user privacy.
     */
    'advanced_matching_enabled' => env('META_PIXEL_ADVANCED_MATCHING_ENABLED', true),

    /*
     * Enable or disable script rendering. Useful for local development.
     */
    'enabled' => env('META_PIXEL_ENABLED', false),

    /*
     * This is used to test server events
     */
    'test_event_code' => env('META_TEST_EVENT_CODE'),
];

如果您计划使用闪存功能，则必须注册 MetaPixelMiddleware

全局中间件

->withMiddleware(function (Middleware $middleware) {
     $middleware->append(MetaPixelMiddleware::class);
})

或将中间件分配给路由（如果您有管理员路由，则推荐使用）

Route::group(['middleware' => [MetaPixelMiddleware::class]], static function () {

});

使用 - Meta Pixel

在 Blade 中包含脚本

在 head 标签打开后插入 head 视图，在 body 标签打开后插入 body 视图

<!DOCTYPE html>
<html>
<head>
    <x-metapixel-head/>
</head>
<body>
    <x-metapixel-body/>
</body>

如果您使用 UUID 作为用户 ID，则应在 head 组件中添加 userIdAsString 属性

<head>
    <x-metapixel-head :userIdAsString="true"/>
</head>

要添加事件，请使用 track() 函数。

// CheckoutController.php
use Combindma\FacebookPixel\Facades\MetaPixel;

public function index()
{
    MetaPixel::track('Purchase', ['currency' => 'USD', 'value' => 30.00]);
    return view('thank-you');
}

这将渲染

<html>
  <head>
    <script>/* Meta pixel's base script */</script>
    <!-- ... -->
  </head>
  <body>
  <script>fbq('track', 'Purchase', {"currency":"USD","value":30});</script>
  <!-- ... -->
</html>

您还可以为任何事件指定一个唯一的事件 ID，这样，如果您计划使用 conversions API，您就可以避免重复。

//For example your order id
MetaPixel::track('Purchase', ['currency' => 'USD', 'value' => 30.00], '123456');

//Or create a unique id using
$eventId = uniqid('ViewContent_', true);
MetaPixel::track('ViewContent', [], $eventId);

为下一次请求闪存数据

此包还可以设置事件在下次请求上渲染。这对于在内部重定向后设置数据非常有用。

// ContactController.php
use Combindma\FacebookPixel\Facades\MetaPixel;

public function postContact()
{
    // Do contact form stuff...
    MetaPixel::flashEvent('Lead', [
        'content_name' => 'Auto Insurance',
        'content_category' => 'Quote',
        'value' => 400.00,
        'currency' => 'USD'
    ]);
    return redirect()->action('ContactController@getContact');
}

在表单提交后，以下事件将在联系页面上解析

<html>
<head>
    <script>/* Meta pixel's base script */</script>
    <!-- ... -->
</head>
<body>
<script>
    fbq(
        'track', 'Lead', {
            'content_name': 'Auto Insurance',
            'content_category': 'Quote',
            'value': 40.00,
            'currency': 'USD'
        }
    );
</script>
<!-- ... -->
</html>

可用方法

use Combindma\FacebookPixel\Facades\MetaPixel;

// Retrieve your Pixel id
$id = MetaPixel::pixelId();
// Set Pixel id on the fly
MetaPixel::setPixelId('XXXXXXXX');
// Check whether script rendering is enabled
$enabled = MetaPixel::isEnabled(); // true|false
// Enable and disable script rendering on the fly
MetaPixel::enable();
MetaPixel::disable();
// Add event to the event layer (automatically renders right before the pixel script). Setting new values merges them with the previous ones.
MetaPixel::track('eventName', ['attribute' => 'value']);
MetaPixel::track('eventName', ['attribute' => 'value'], 'event_id'); //with an event id
MetaPixel::track('eventName'); //without properties 
MetaPixel::track('eventName', [], 'event_id'); //with an event id but without properties
// Flash event for the next request. Setting new values merges them with the previous ones.
MetaPixel::flashEvent('eventName', ['attribute' => 'value']);
MetaPixel::flashEvent('eventName', ['attribute' => 'value'], 'event_id'); //with an event id
MetaPixel::flashEvent('eventName'); //without properties
//Clear the event layer.
MetaPixel::clear();

自定义事件

您还可以跟踪您网站上的特定自定义事件。此功能不适用于闪存事件。

use Combindma\FacebookPixel\Facades\MetaPixel;

// In your controller
MetaPixel::trackCustom('CUSTOM-EVENT-NAME', ['custom_parameter' => 'ABC', 'value' => 10.00, 'currency' => 'USD']);
//With an event ID
MetaPixel::trackCustom('CUSTOM-EVENT-NAME', ['custom_parameter' => 'ABC', 'value' => 10.00, 'currency' => 'USD'], 'EVENT_ID');

这将渲染

<html>
  <head>
    <script>/* Meta Pixel's base script */</script>
    <!-- ... -->
  </head>
  <body>
  <script>
      fbq('trackCustom', 'CUSTOM-EVENT-NAME', {'custom_parameter': 'ABC', 'value': 10.00, 'currency': 'USD'});
      /* If you specify the event ID */
      fbq('trackCustom', 'CUSTOM-EVENT-NAME', {'custom_parameter': 'ABC', 'value': 10.00, 'currency': 'USD'}, { eventID : 'EVENT_ID' });
  </script>
  <!-- ... -->
</html>

高级匹配

该软件包默认提供高级匹配功能。我们从经过身份验证的用户那里检索电子邮件和用户 ID，并将其作为第三个参数包含在 Pixel 基础代码 fbq('init') 函数调用中。您可以通过在 .env 文件中添加 META_PIXEL_ADVANCED_MATCHING_ENABLED=false 来禁用此功能

<html>
<head>
    <script>
        /* Meta pixel's base script */
        <!-- ... -->
        fbq('init', '{PixelID}', {
            em: 'email@email.com', //Email provided with Auth::user()->email
            external_id: 12345, //User id provided with Auth::id()
        });
    </script>
    <!-- ... -->
</head>
<body>
<!-- ... -->
</html>

可宏化

向页面添加事件可能是一个重复的过程。由于此软件包不打算对您的事件外观提出意见，因此 MetaPixel 是可宏化的。

use Combindma\FacebookPixel\Facades\MetaPixel;

//include this in your macrobale file
MetaPixel::macro('purchase', function ($product) {
    MetaPixel::track('Purchase', [
        'currency' => 'EUR',
        'value' => $product->price
    ]);
});

//in your controller
MetaPixel::purchase($product);

用法 - 转化 API

如果您计划使用转化 API 功能，您应首先在 .env 文件中指定令牌。

对于每个请求，您应指定一个唯一的事件 ID，以处理像素重复事件和转化 API。

以下是开始的方法

use Combindma\FacebookPixel\Facades\MetaPixel;
use FacebookAds\Object\ServerSide\Content;
use FacebookAds\Object\ServerSide\CustomData;
use FacebookAds\Object\ServerSide\DeliveryCategory;
use FacebookAds\Object\ServerSide\UserData;

//Prepare User Data first.
// By default, the IP Address, User Agent and fbc/fbp cookies are added.
$user_data = MetaPixel::userData()->setEmail('joe@eg.com')->setPhone('12345678901');

$content = (new Content())
    ->setProductId('product123')
    ->setQuantity(1)
    ->setDeliveryCategory(DeliveryCategory::HOME_DELIVERY);
    
$custom_data = (new CustomData())
    ->setContents(array($content))
    ->setCurrency('usd')
    ->setValue(123.45);
    
$eventId = uniqid('prefix_');
    
//send request
MetaPixel::send('Purchase', $eventId ,$custom_data, $user_data);

如果您没有指定 $user_data 参数，则默认情况下，如果用户已通过身份验证，我们将从 Auth::user() 中检索电子邮件和 ID。我们使用用户 ID 作为 Meta Pixel 和转化 API 中的相同外部 ID

MetaPixel::send('Purchase', $eventId, $custom_data);

如果您想测试服务器事件，您需要在 .env 文件中指定 FACEBOOK_TEST_EVENT_CODE。默认情况下，此测试代码将发送到所有 API 请求。

所以，测试完成后，请务必删除。

您可以使用 Playload Helper 了解要发送的请求的更多信息。

测试

composer test

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全漏洞

请查看我们的安全策略，了解如何报告安全漏洞：

鸣谢

许可协议

MIT 许可协议（MIT）。有关更多信息，请参阅许可文件。

mina / laravel-facebook-pixel

维护者

详情