PHP SDK

Track revenue, signups, product usage, and user identity from your PHP backend using the official Ripples SDK.

Server-side tracking. Use the PHP SDK to send events from your backend — ideal for tracking payments processed server-side, webhooks, or any event that shouldn't go through the browser.

Install

composer require ripplesanalytics/ripples-php

Add your secret key to your .env:

RIPPLES_SECRET_KEY=priv_your_secret_key

Your secret key can be found in your Ripples dashboard under Settings → API Keys.

Quick start

use Ripples\Ripples;

$ripples = new Ripples();

// Track a payment
$ripples->revenue(49.99, 'user_123');

// Track a signup
$ripples->signup('user_123', ['email' => '[email protected]']);

// Track product usage
$ripples->track('created a budget', 'user_123', ['area' => 'budgets']);

// Identify / update a user
$ripples->identify('user_123', ['email' => '[email protected]']);

Track revenue

Call revenue() whenever a payment is processed on your server:

$ripples->revenue(49.99, 'user_123');

Pass extra context as a third argument. Any key that isn't a known field becomes a custom property automatically:

$ripples->revenue(49.99, 'user_123', [
    'email'          => '[email protected]',
    'currency'       => 'EUR',
    'transaction_id' => 'txn_abc123',
    'name'           => 'Pro Plan',
    'plan'           => 'annual',      // custom property
    'coupon'         => 'WELCOME20',   // custom property
]);

Refunds are negative revenue:

$ripples->revenue(-29.99, 'user_123', ['transaction_id' => 'txn_abc123']);

Parameters

Parameter Type Description
amount required float Revenue amount in your default currency. Use negative values for refunds.
user_id required string Your internal user ID.
properties optional array Additional properties: email, currency, transaction_id, name, plus any custom keys.

Track product usage

Call track() when a user does something meaningful in your product. This powers the Activation dashboard — showing which product areas drive engagement and conversion.

// User did something meaningful
$ripples->track('created a budget', 'user_123', [
    'area' => 'budgets',   // optional: group into a product area
]);

// User added their 10th transaction — we consider this their activation moment
$ripples->track('added transaction', 'user_123', [
    'area'      => 'transactions',
    'activated' => true,    // marks THIS occurrence as the activation moment, not every "added transaction"
]);

How it works. Ripples auto-detects activation moments (first occurrence per user per action), computes adoption rates by product area, and correlates usage patterns with retention and payment.

Parameters

Parameter Type Description
actionName required string What the user did. Be specific: 'created a budget', not 'budgets'.
userId required string Your internal user ID.
area optional string Product area this action belongs to (e.g. 'budgets', 'reports'). Groups actions in the dashboard.
activated optional bool Set to true on the specific occurrence when activation happens for this user. This does not mark the event type as an activation event — it marks this particular moment as when the user activated. For example, 'sent message' is a regular event, but when a user sends their 10th message you may consider that their activation moment and send that occurrence with activated => true.

Track signups

Call signup() when a new user registers:

$ripples->signup('user_123', [
    'email'    => '[email protected]',
    'name'     => 'Jane Smith',
    'referral' => 'twitter',   // custom property
    'plan'     => 'free',       // custom property
]);

Laravel example

use Ripples\Ripples;

class AuthController extends Controller
{
    public function register(Request $request)
    {
        $user = User::create([...]);

        $ripples = new Ripples();
        $ripples->signup($user->id, [
            'email'           => $user->email,
            'name'            => $user->name,
            'ripples_visitor_id' => $request->cookie('_rpl_vid'),
        ]);

        return $user;
    }
}

Tip: pass the visitor ID. Include ripples_visitor_id with the value from the _rpl_vid cookie to link this signup back to the anonymous browsing session and correct traffic source attribution.

Identify users

Call identify() to update user traits at any time — on login, plan change, profile update, etc.:

$ripples->identify('user_123', [
    'email'      => '[email protected]',
    'name'       => 'Jane Smith',
    'avatar_url' => 'https://example.com/avatars/jane.jpg',
    'company'    => 'Acme Inc',  // custom property
    'role'       => 'admin',      // custom property
]);

Properties

Key Type Description
email optional string User's email address. Shown in the visitor profile and used for Stripe revenue attribution.
name optional string Display name shown in the visitor profile.
avatar_url optional string URL to the user's avatar image. Displayed in the visitor profile. Also accepted as avatar.
[custom] optional string | number Any additional traits you want to attach to the user (e.g. plan, company, role).

Error handling

use Ripples\RipplesException;

try {
    $ripples->revenue(49.99, 'user_123');
} catch (RipplesException $e) {
    // Log or handle gracefully — never block the user flow
    Log::warning('Ripples error: ' . $e->getMessage());
}

Configuration

The SDK reads RIPPLES_SECRET_KEY from your environment automatically. You can also pass it explicitly:

$ripples = new Ripples('priv_explicit_key', [
    'base_url' => 'https://your-domain.com/api', // self-hosted
    'timeout'  => 10, // seconds (default: 5)
]);

The self-hosted URL can also be set via env:

RIPPLES_URL=https://your-domain.com/api

Configuration options

Option Default Description
base_url https://api.ripples.sh API endpoint. Override for self-hosted deployments.
timeout 5 HTTP request timeout in seconds.

Custom HTTP client

Extend the class and override post() to use Guzzle, Symfony HttpClient, or any other HTTP library:

class MyRipples extends \Ripples\Ripples
{
    protected function post(string $path, array $data): array
    {
        // your custom implementation using Guzzle, etc.
    }
}

Requirements

  • PHP 8.1+
  • ext-curl
  • ext-json