php ga4
1.0.0
composer require alexwestergaard/php-ga4유럽 연합에서는 Google Analytics가 기본적으로 GDPR을 준수하지 않는다고 통보했습니다. 이는 프런트엔드 클라이언트가 방문자의 IP 주소 및 장치 정보와 같은 세부 정보를 이벤트와 함께 보내기 때문입니다. 이는 유럽 지역 내부의 중개 서버를 사용하면 피할 수 있습니다.
설정에는 측정 ID 와 API 비밀번호가 필요합니다. 관리자(왼쪽 하단) -> 계정 -> 데이터 스트림 -> {내 스트림}으로 이동합니다. 여기서 상단에 측정 ID가 있고 페이지 약간 아래에 '측정 프로토콜을 위한 API 비밀번호'가 있는데, 여기에서 직접 API secret 만들 수 있습니다.
Administrator (왼쪽 하단)로 이동한 다음 Account -> Data Streams -> 스트림을 선택합니다.
여기에서는 Api Secrets for Measurement Protocol 맨 위 및 아래에서 Measurement-ID 찾을 수 있으며, 여기에서 API Secret 직접 만들 수 있습니다.
자격 증명을 얻은 후에는 다음과 같이 Analytics를 초기화할 수 있습니다.
use AlexWestergaard PhpGa4 Analytics ;
$ analytics = Analytics:: new (
measurement_id: ' G-XXXXXXXX ' ,
api_secret: ' xYzzX_xYzzXzxyZxX ' ,
debug: true | false #Default: False
); 서버 측 태그 지정은 프런트엔드 클라이언트를 대체할 수 없으며 세션 시작은 gtag.js 클라이언트를 통해 이루어져야 합니다. 기본 흐름은 다음과 같이 발생합니다.
_ga 및 _gid 쿠키를 Client/GTAG.js로 다시 보냅니다._ga (또는 _gid )를 사용하여 이벤트를 보내거나 채웁니다. 참고: Google Analytics에서 세션 쿠키를 얻지 않고도 이벤트를 백엔드로 푸시하는 것이 전적으로 가능합니다. 그러나 백엔드를 통해 해당 정보를 푸시하는 방법을 찾지 못하면 GTAG.js 요청 내에 포함된 정보를 잃게 됩니다. _ga 및 _gid 세션을 고유하게 생성된 ID로 바꿀 수 있습니다.
모든 요청은 이 구조를 따라야 하며 Google Analytics가 이를 수락할 수 있는 이벤트를 하나 이상 포함해야 합니다.
Analytics [
Events [
Event {
Parameters
? Items [
Item Parameters
]
}
]
User Properties [
Properties {
Key: Value
}
]
? Consent {
Key: Value
}
? User Data {
Key: Value
}
]이는 설명서에 표시된 사전 구축된 이벤트 목록입니다. 모든 이벤트에는 각 이벤트의 트리거 위치를 찾기 위한 다음 매개변수가 있습니다.
// Manual setting of each event
$ event -> setLanguage (string $ var );
$ event -> setPageLocation (string $ var );
$ event -> setPageReferrer (string $ var );
$ event -> setPageTitle (string $ var );
$ event -> setScreenResolution (string $ var );
// Fillable for multiple events
$ eventPage = AlexWestergaard PhpGa4 Helper EventParamsHelper ();
$ event -> setEventPage ( $ eventPage );이 라이브러리는 백엔드 서버측 추적을 위해 구축되었지만 대부분의 이벤트는 Javascript 또는 Websocket을 사용하는 프런트엔드를 통해 트리거될 것입니다. 두 가지 예가 있습니다. 하나는 기록된/대기열에 추가된 이벤트를 위한 순수 백엔드로, 다른 하나는 프런트엔드에서 백엔드 간 통신을 위한 것입니다.
use AlexWestergaard PhpGa4 Exception ;
use AlexWestergaard PhpGa4 Analytics ;
use AlexWestergaard PhpGa4 Event ;
use AlexWestergaard PhpGa4 Item ;
// require vendor/autoload.php
$ visitors = getVisitorsAndEvents (); // pseudo function, make your own logic here
foreach ( $ visitors as $ collection ) {
// Group of events, perhaps need logic to change from json or array to event objects
// Maybe its formatted well for the > ConvertHelper::parseEvents([...]) < helper
$ groups = $ collection [ ' events ' ];
// If gtag.js, this can be the _ga or _gid cookie
// This can be any kind of session identifier
// Usually derives from $_COOKIE['_ga'] or $_COOKIE['_gid'] set by GTAG.js
$ visitor = $ collection [ ' session_id ' ];
// load logged in user/visitor
// This can be any kind of unique identifier, readable is easier for you
// Just be wary not to use GDPR sensitive information
$ user = $ collection [ ' user_id ' ];
// Render events grouped on time (max offset is 3 days from NOW)
foreach ( $ groups as $ time => $ data ) {
try {
$ analytics = Analytics:: new ( $ measurementId , $ apiSecret )
-> setClientId ( $ visitor )
-> setTimestampMicros ( $ time );
if ( $ user !== null ) {
$ analytics -> setUserId ( $ user );
}
$ analytics -> addUserParameter (... $ data [ ' userParameters ' ]); // pseudo logic for adding user parameters
$ analytics -> addEvent (... $ data [ ' events ' ]); // pseudo logic for adding events
$ analytics -> post (); // send events to Google Analytics
} catch ( Exception Ga4Exception $ exception ) {
// Handle exception
// Exceptions might be stacked, check: $exception->getPrevious();
}
}
} // array< array< eventName, array<eventParams> > >
axios . post ( "/your-api-endpoint/ga4-event-receiver" , [
// Note each event is its own object inside an array as
// this allows to pass the same event type multiple times
{
addToCart : {
currency : "EUR" ,
value : 13.37 ,
items : [
{
item_id : 1 ,
item_name : "Cup" ,
price : 13.37 ,
quantity : 1 ,
} ,
] ,
} ,
} ,
] ) ; use AlexWestergaard PhpGa4 Helper ConvertHelper ;
use AlexWestergaard PhpGa4 Exception ;
use AlexWestergaard PhpGa4 Analytics ;
use AlexWestergaard PhpGa4 Event ;
// require vendor/autoload.php
try {
$ events = ConvertHelper:: parseEvents ( $ _POST );
Analytics:: new ( $ measurementId , $ apiSecret )
-> addEvent (... $ events )
-> post ();
} catch ( Exception Ga4Exception $ exception ) {
// Handle exception
// Exceptions might be stacked, check: $exception->getPrevious();
} 나만의 맞춤 이벤트를 만들 수 있습니다. 필요한 것은 AlexWestergaardPhpGa4FacadeTypeEventType 외관/인터페이스를 구현하고 채우는 것뿐입니다. 편리한 기능을 원한다면 AlexWestergaardPhpGa4HelperEventHelper 에서 이벤트를 확장하고 적절하다고 판단되는 대로 덮어쓸 수 있습니다.
// EventHelper implements AlexWestergaardPhpGa4FacadeTypeEventType
class ExampleEvent extends AlexWestergaard PhpGa4 Helper EventHelper
{
// variables should be nullable as unset() will set variable as null
protected null | mixed $ my_variable ;
protected null | mixed $ my_required_variable ;
// Arrays should always be instanciated empty
protected array $ my_array = [];
public function getName (): string
{
return ' example_event ' ;
}
public function getParams (): array
{
return [
' my_variable ' ,
' my_array ' ,
];
}
public function getRequiredParams (): array
{
return [
' my_required_variable ' ,
];
}
public function setMyVariable ( string $ value )
{
$ this -> my_variable = $ value ;
return $ this ; // Allows chained events
}
public function setMyRequiredVariable ( string $ value )
{
$ this -> my_required_variable = $ value ;
return $ this ; // Allows chained events
}
} GA4용 측정 프로토콜에는 Analytics 생성자의 debug 매개변수를 사용하여 활성화할 수 있는 디버그 기능이 있습니다.
$ analytics = Analytics:: new (
measurement_id: ' G-XXXXXXXX ' ,
api_secret: ' xYzzX_xYzzXzxyZxX ' ,
debug: true // default: false
); Debug 활성화되면 이벤트가 https://www.google-analytics.com/debug/mp/collect 로 전송되며 여기서 문제는 GA4Exception으로 포착됩니다( $exception->getPrevious() 스택 주의). 그러한 응답은 다음과 같습니다:
{
"validationMessages" : [
{
"fieldPath" : " events " ,
"description" : " Event at index: [0] has invalid name [_badEventName]. Names must start with an alphabetic character. " ,
"validationCode" : " NAME_INVALID "
}
]
} 참고: 이 라이브러리는 분석( $analytics->addEvent(...) )에 추가될 때 이벤트의 형식이 올바른지 이미 검증합니다.
두 가지 중요한 사항:
debugView 에 표시되는 방법은 없습니다. page_view 이벤트는 작동하지만 공식 문서에 문서화되어 있지 않으므로 이에 의존하지 마십시오. 
