Distribution Events

Distribution events power Siren’s scheduled reward system. Unlike the per-conversion program flow, distributions reward collaborators on a recurring schedule based on aggregate performance over time. The events here span two domains: distributions (Siren\Distributions\Core\Events) and metrics (Siren\Metrics\Core\Events). Together they form a pipeline that goes from heartbeat tick to metric accumulation to allocation to obligation.

The distribution pipeline

The distribution system works on a heartbeat. A scheduler fires the heartbeat event on a regular interval. That event triggers a check for distributions whose trigger date has passed. Each ready distribution is processed, which creates allocations for qualifying collaborators. Each allocation becomes an obligation, entering the same fulfillment pipeline that program-based conversions use.

DistributionHeartbeatInitialized is the scheduler trigger that kicks off distribution processing. It carries no data. When it fires, the distribution system queries for all distributions whose trigger date has passed and processes each one.

DistributionCompleted fires when a distribution period is processed. The listener that handles this event calculates the reward pool, determines each qualifying collaborator’s share based on their accumulated metrics, and creates allocation records.

AllocationCompleted fires when an individual collaborator’s share of a distribution has been calculated and recorded. The allocation’s value becomes the obligation amount, which enters the same pending-to-fulfilled lifecycle as program-based obligations.

Metric events

Metrics are the performance indicators that distributions use to calculate each collaborator’s share. They accumulate continuously between distribution periods.

MetricsTriggered fires when new metric data is recorded. Different trigger strategies produce metrics from different sources: a sale-based strategy fires this event when a sale occurs, a visit-based strategy fires it when a site visit is tracked. The strategy ID tells downstream listeners which strategy is responsible.