Skip to main content

Surface the customer’s referral link and live referral credit in an add-on dashboard widget

Premium Beginner

A podcaster who has to visit benecaster.com to see what their referrals have earned mostly does not look. Putting the number where they already are — a dashboard widget, an add-on’s settings screen — is the difference between a referral programme people use and one they forget.

The link and code come from values already stored on the site, refreshed once a day when Benecaster checks in with the licence server. They never change, so the cached copy is right, and reading them makes no network call. The balance is different: it must be live. benecaster_get_live_referral_balance() asks the licence server at most once every five minutes and returns null when it has no answer.

On null, show no figure at all. Link to the podcaster’s account page instead. Never fall back to benecaster_get_referral_credit_cents(): that is the daily cache, and its 0 cannot tell “no credit” from “the lookup failed”. The balance is per customer, not per site, so word it as credit on the podcaster’s account.

Check for a referral code before rendering anything. On a site whose licence server has not supplied one, the functions return nothing, and a widget that registers regardless is an empty box on every such install. Test for the code first and register nothing when it is absent.

When to Use This

Use this when your add-on has an admin surface — a dashboard widget, a settings panel, an onboarding screen — and you want to show the podcaster their referral link and what they’ve earned without sending them to benecaster.com to check.

The Functions

Function Returns
benecaster_get_referral_code() The podcaster’s referral code, or null if none is available
benecaster_get_referral_link() The full referral URL, or null
benecaster_get_live_referral_balance() The live balance in integer cents, or null when there is no live answer

How It Works

Register the widget on wp_dashboard_setup, but check benecaster_get_referral_code() first and return early when it’s null, so the widget never appears on an install with no referral data. Inside the render callback, print the link, then branch on the live balance: null gets a link to the account page, a positive figure is shown as credit on the account, and zero reads as none yet.

Notes

The live call is for wp-admin, cron and admin requests. It asks the licence server at most once every five minutes per site and reuses the answer in between, so a balance can be up to five minutes old. On a front-end request it never calls out: it returns a reused answer or null. Call it from admin screens and dashboard widgets, not from theme templates.

Guard on the referral code. It is null on a site whose licence server has not supplied one. Registering the widget unconditionally means an empty box on every unlicensed install.

Prefer benecaster_get_referral_link() over building the URL from the code. If the link format changes, the cached value updates on the next validation run; a hand-built URL does not.

The value is in cents. Divide by 100 before formatting, and format for the podcaster’s locale rather than assuming dollars.

If your add-on notifies the customer about referral activity — an admin notice, a digest line — honour their email opt-out too: if ( ! benecaster_get_notify_referral_updates() ) { return; }. It reflects the same checkbox that switches off Benecaster’s own referral-credit emails, and it defaults to true when the licence server has not answered yet. A widget that only displays the balance on request does not need the check.

Code

<?php
// In an add-on dashboard widget callback (wp-admin, so the live call is allowed):
add_action( 'wp_dashboard_setup', function (): void {
    $code = benecaster_get_referral_code();
    if ( null === $code ) {
        return; // License server has not (yet) supplied a referral code.
    }
    wp_add_dashboard_widget(
        'my_addon_referral_status',
        __( 'Benecaster referral status', 'my-addon' ),
        static function () use ( $code ): void {
            $link    = benecaster_get_referral_link() ?? "https://benecaster.com/ref/{$code}";
            $balance = benecaster_get_live_referral_balance(); // null = no live answer.

            printf(
                '<p>%s <code>%s</code></p>',
                esc_html__( 'Your referral link:', 'my-addon' ),
                esc_html( $link )
            );

            if ( null === $balance ) {
                printf(
                    '<p><a href="%s" target="_blank" rel="noopener noreferrer">%s</a></p>',
                    esc_url( \Benecaster\License\LicenseManager::REFERRAL_DASHBOARD_URL ),
                    esc_html__( 'See your current referral credit on benecaster.com', 'my-addon' )
                );
            } elseif ( $balance > 0 ) {
                printf(
                    '<p>%s</p>',
                    esc_html( sprintf(
                        /* translators: %s: formatted dollar amount */
                        __( '%s in referral credit on your Benecaster account.', 'my-addon' ),
                        '$' . number_format( $balance / 100, 2 )
                    ) )
                );
            } else {
                esc_html_e( 'No referral credit on your Benecaster account yet.', 'my-addon' );
            }
        }
    );
} );

View on GitHub →

Need this built rather than just documented? See our services →

Powered by