Guide to Integrating Facebook Pixel and Conversions API on 1C-Bitrix
Based on official Facebook Pixel and Conversions API documentation.
The Facebook Pixel does not work "out of the box" on Bitrix — and it's not about code complexity, but that the standard script inclusion mechanism conflicts with caching and the event model. Basic pixel code is inserted into the header via header.php or site settings, but without event transmission it's just a visit counter. We perform a comprehensive turnkey integration with guaranteed correct transmission of all events. Typical integration cost ranges from $500 to $1,500 depending on the number of events and API requirements.
Why Standard Pixel Integration Doesn't Work
Direct script insertion into header.php seems simple but causes many problems. First, when changing the template or updating components, the code is lost. Second, when using composite templates (bitrix:page.polymorph), some blocks are cached, and the script does not execute on cached pages. The result — missed conversions and inaccurate data. Our experience shows that over 30% of projects are initially set up this way, and we fix these errors within 3–5 days.
Where the Base Code Lives and Why It's Problematic
The site template in Bitrix stores header.php in /bitrix/templates/<template_name>/. Inserting the script directly into the file works but is inconvenient: when changing the template, the code is lost, and when using composite templates, cached blocks may not fire the pixel.
It is better to use the bitrix:main.include component with the parameter AREA_FILE_SHOW = head, or add the script via the OnEpilog event handler in /bitrix/php_interface/init.php:
AddEventHandler("main", "OnEpilog", function() { $pixelId = COption::GetOptionString("main", "fb_pixel_id", ""); if ($pixelId) { echo '<script>/* FB Pixel code with id: ' . htmlspecialchars($pixelId) . ' */</script>'; } }); The pixel ID is stored in the b_option table (module main) via COption::SetOptionString. This approach ensures the code is not lost when changing templates and executes on every page.
Standard Events and Catalog Data Transfer
For e-commerce, three events are important: ViewContent, AddToCart, and Purchase. All must transmit product parameters — content_ids, content_type, value, currency.
ViewContent — fires on the product detail page. The bitrix:catalog.element component generates the page; product data is available in $arResult. We customize template.php of the component and add the JS call fbq('track', 'ViewContent', {...}) with $arResult["ID"] and $arResult["PRICES"].
AddToCart — more problematic. Adding to cart in Bitrix happens via an AJAX request to sale.basket.basket or directly via CSaleBasket::Add(). The pixel event should fire in the JS callback after a successful response. In the Bitrix kernel, the event OnSaleBasketItemAdd is responsible — it can be used for server-side sending via CAPI, but that's a separate story.
Purchase — fires on the thank_you page or in the bitrix:sale.order.ajax component after successful checkout. $arResult["ORDER_ID"] contains the order ID; we take the amount from CSaleOrder::GetByID(). Ensure the exact amount with delivery and discounts is passed.
Why You Should Add Conversions API
Browser pixel loses data due to ad blockers and iOS restrictions. Facebook recommends duplicating events via the server-side Conversions API. The request goes from your server to graph.facebook.com/v18.0/<pixel_id>/events with an access token. On Bitrix, this is implemented via CURLFile or the standard \Bitrix\Main\Web\HttpClient. We attach a handler to the OnSaleOrderSaved event and send Purchase with a hashed email (sha256) and event_id for deduplication with the browser event. In current versions of the main module, HttpClient is available — we use it instead of file_get_contents to avoid dependency on allow_url_fopen configuration. Server-side events with CAPI are 2x more reliable than browser-only pixel tracking. Over 80% of our clients see improved tracking after switching to CAPI.
| Parameter | Browser Pixel | Conversions API |
|---|---|---|
| Ad blockers | Does not work | Always works |
| iOS 14.5+ | Up to 30% data loss | All events transmitted |
| Deduplication | Requires event_id | Requires event_id |
| Latency | Instant | Up to several seconds |
| Setup complexity | Low | Medium |
Technical Details on Deduplication
Deduplication relies on a unique event_id generated per transaction. In the browser, it's passed as the fourth parameter of fbq('track', 'Purchase', data, {eventID: 'order_123'}). On the server, the same ID is included in the payload under event_id. Facebook then matches browser and server events by this ID and counts them as one. Without matching IDs, both events are treated as separate conversions, inflating numbers.Turnkey Setup Process
- Analytics — study of the current site structure, identification of event types.
- Design — determine code insertion points, choose pixel ID storage method.
- Implementation — add pixel code via OnEpilog, customize component templates for e-commerce events.
- Conversions API integration — configure server-side sending on the OnSaleOrderSaved event.
- Testing — verify using Facebook Pixel Helper and Events Manager.
- Deployment — push to production, monitor for 24 hours.
Setup typically takes 2–4 days for a standard e-commerce site.
What's Included
- Setup of base pixel code with ID stored in module options.
- Implementation of ViewContent, AddToCart, and Purchase events with correct product parameters.
- Conversions API integration with email hashing and event_id.
- Deduplication of server and browser events.
- Instructions for self-verification and test documentation.
- 30-day performance guarantee after delivery.
Verification
After setup, check using Facebook Pixel Helper (Chrome extension) and via Events Manager in your Facebook account — the "Test Events" tab. In test mode, Conversions API shows the actual payload with validation errors. A common problem: the event is duplicated — browser and server arrive without event_id. Without deduplication, Facebook counts them as two separate conversions. The event_id must be the same in the JS call fbq('track', 'Purchase', data, {eventID: 'order_123'}) and in the server request. Our experience shows that proper deduplication increases tracking accuracy to 95%.
Our Expertise
Over 8 years of experience integrating Bitrix with external services. We have completed over 50 successful integrations on pixel and API setup for e-commerce. We use certified approaches and official Facebook recommendations. Contact us for an exact cost estimate — we will evaluate your project within one business day.