Skip to main content

React to a free follower signup

Free Intermediate

The follower signup shortcode creates a WordPress user, issues them a follower token, and then fires benecaster_follower_signed_up( int $user_id, int $show_id, string $tier_slug ).

The hook means one thing only: a follower token was just created — do not read it as “a welcome email is about to go out.” Three paths diverge underneath it:

  • A new address — the token is created, this fires, and the welcome mail follows.
  • An address that already follows the show — no token is minted, so this action does not
    fire at all    . They get the already following mail instead.
  • A visitor who is already signed in — a token is created and this does fire, with
    both mails suppressed. No email is sent anywhere on that path.

So a listener that assumes mail is imminent is wrong on the third path, and a listener that counts this to count welcome emails will over-count.

Signup is idempotent, and the hook reflects that: it fires only when a follower token is actually inserted. A returning follower signing up again succeeds silently without a second token, a second account, or a second welcome email.

The hook and benecaster_follower_signup()‘s created flag answer different questions, and they diverge. This hook fires when a token is created; created reports whether a WordPress user was. Somebody who already had an account on the site but no token for this show fires this hook and comes back with created: false. If you are branching on created to decide whether somebody is new to the show, this hook is the more reliable signal.

benecaster_follower_tier_slug filters the tier slug, which is how a multi-show site gives each show its own follower tier.

Tag a Follower in Your ESP on Signup

Use benecaster_follower_signed_up to sync the new follower to an external system immediately after the token is inserted. This action does not fire for returning followers — a duplicate signup silently succeeds without re-inserting the token, so the hook only fires for genuinely new followers. Do not tie the sync to the welcome email’s timing — see above, the mail does not always follow, and never does for a signed-in signup.

Use Show-specific Follower Slugs

The follower slug appears in the feed URL — /podcast-feed/{show}/{slug}/?token=… — so on multi-show sites a per-show slug reads better than the shared default. With the filter shown below, a follower on a show with slug my-show gets tier_slug = 'my-show-follower'.

The slug you return must not collide with a tier slug generated by your membership bridge. A suffix like -follower keeps it clear of them.

The slug is cosmetic — it does not gate anything. A follower feed carries the public feed’s episodes, so there is no per-episode follower availability for the slug to target.

Changing it on a live show changes the follower feed URL Benecaster displays and hands out from that point on. Feeds already sitting in podcast apps keep working: the path segment is not read when a feed request is resolved — the token is — so an old URL goes on serving the same episodes it served before.

Build a Custom Signup UI

The shortcode is not the only entry point. For wholly custom signup UIs — a popup overlay, a Gutenberg block with extra fields, a WP-CLI command — call benecaster_follower_signup():

$result = benecaster_follower_signup( $show_id, $email, $name );
if ( is_wp_error( $result ) ) {
    // render the error in your UI — the messages are deliberately non-enumerating
}

Calling this twice for the same email and show returns success without inserting a second token row, so a UI that allows double-clicks won’t create duplicate accounts or re-send the welcome email.

Prefer it over issuing a token yourself. It applies the follower token type, the idempotency check, and the welcome email in the right order; reproducing that by hand is how duplicate accounts get created.

Full worked example, including the AJAX handler and the enumeration rules: Build a custom follower signup UI.

Related

Code

<?php
// Tag a follower in your ESP without enabling the Email Integrations add-on.
add_action( 'benecaster_follower_signed_up', function ( int $user_id, int $show_id, string $tier_slug ): void {
    $user = get_userdata( $user_id );
    if ( ! $user instanceof \WP_User ) {
        return;
    }
    my_esp_tag_subscriber( $user->user_email, 'benecaster_follower' );
}, 10, 3 );

// Use a show-specific follower slug so the feed URL reads sensibly per show.
add_filter( 'benecaster_follower_tier_slug', function ( string $tier_slug, int $show_id ): string {
    $show = get_post( $show_id );
    return $show ? $show->post_name . '-follower' : $tier_slug;
}, 10, 2 );

View on GitHub →

Hooks Used

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

Powered by