Event Types and Payloads

This page serves as a technical reference for the six core event types supported by the rudder-php-sdk. Each event type is mapped to a specific method in the Rudder facade and the Client class. All methods require a $message array containing specific fields to ensure successful delivery to the RudderStack data plane.

Overview of Event Flow

When an event method is called, the SDK performs validation before passing the payload to the underlying Client. The Client then enriches the message with metadata (like timestamp and messageId) and enqueues it for the configured consumer transport.

Data Mapping Architecture

The following diagram illustrates how natural language event concepts map to the internal PHP classes and methods.

Event Mapping Diagram

Sources: lib/Rudder.php67-189 bin/analytics41-82

---

Required Fields and Validation

Across most event types, the SDK enforces a "User Identity" requirement. A message must contain either a userId or an anonymousId to be considered valid.

Field	Type	Description
userId	string	The unique identifier for the user in your database.
anonymousId	string	A pseudo-unique identifier (e.g., session ID or device ID) used before a user is identified.

The validation logic is centralized in Rudder::validate() lib/Rudder.php99-104

---

Event Type Reference

1. Identify

The identify call ties a user to their actions and records traits about them.

• Method: Rudder::identify(array $message) lib/Rudder.php114-121
• Required: userId OR anonymousId.
• Key Fields: traits (array of user attributes).

Example Payload:

Sources: lib/Rudder.php114-121 examples/sanity-test/Sanity.php71-75

2. Track

The track call records any actions the user performs.

• Method: Rudder::track(array $message) lib/Rudder.php67-75
• Required: event (string), and (userId OR anonymousId).
• Key Fields: properties (array of event metadata).

Example Payload:

Sources: lib/Rudder.php67-75 examples/sanity-test/Sanity.php60-69

3. Page

The page call records when a user views a page on a website.

• Method: Rudder::page(array $message) lib/Rudder.php149-155
• Required: userId OR anonymousId.
• Key Fields: name (string), properties.

Sources: lib/Rudder.php149-155 bin/analytics57-63

4. Screen

The screen call is the mobile equivalent of page, recording screen views.

• Method: Rudder::screen(array $message) lib/Rudder.php165-171
• Required: userId OR anonymousId.
• Key Fields: name (string).

Sources: lib/Rudder.php165-171 examples/sanity-test/Sanity.php107-111

5. Group

The group call associates an identified user with a collective (e.g., an organization or a project).

• Method: Rudder::group(array $message) lib/Rudder.php131-139
• Required: groupId, and (userId OR anonymousId).
• Key Fields: traits (array of group attributes).

Sources: lib/Rudder.php131-139 examples/sanity-test/Sanity.php88-93

6. Alias

The alias call merges two user identities. This is the only call that requires two specific identifiers.

• Method: Rudder::alias(array $message) lib/Rudder.php181-189
• Required: userId AND previousId.

Sources: lib/Rudder.php181-189 bin/analytics73-78

---

Internal Payload Processing

Before transmission, the SDK transforms the input array into a standardized JSON payload. This is handled by the Client class.

Payload Enrichment Logic

Sources: lib/Rudder.php99-104 lib/Rudder.php39-41

Common Optional Fields

While not required by the SDK methods, these fields are often included in the $message array for better downstream analysis:

1. context: An array of technical metadata (e.g., os, library, locale) examples/sanity-test/Sanity.php19-34
2. timestamp: If not provided, the SDK generates a UTC timestamp bin/analytics13
3. integrations: An array to enable/disable specific destinations.

Sources: examples/sanity-test/Sanity.php19-40 bin/analytics13 bin/analytics106-112