Skip to main content

benecaster_get_winback_leads()

Free 
benecaster_get_winback_leads( int $show_id, array $args = [] ): ?array

Returns the cancelled subscribers of a show whose podcast app is still checking the feed: the people behind the win-back count on the Subscribers screen.

It is the same definition as that count, by construction. Both read the same records the same way, so with the default window the number of rows returned is the number on the Subscribers screen. A lead is somebody whose access to this show has ended, who was not a free follower, and whose app has requested the feed with their old feed URL inside the window. Somebody who has since subscribed again is not a lead.

Parameters

Name Type Default Required Description
show_id int — Yes WordPress post ID of the show.
args array [] No Optional. days — the window, in days; defaults to the Subscribers screen's win-back window (30 days, or the feed request log's retention if that is shorter). limit — the most rows to return; 0, the default, returns every row. offset — rows to skip.

Return Value

Type: array|null

One row per lead, most recent check-in first: token_id, user_id, token_prefix (the 8-character display prefix, never the token), token_type, tier_slug (the tier they cancelled from), last_polled_at (UTC, Y-m-d H:i:s), poll_count (polls inside the window), user_agent (the latest poll's) and app (the podcast app that agent belongs to). null when the feed request log is switched off — no data, which is not the same as no leads.

Example

$leads = benecaster_get_winback_leads( $show_id, [ 'limit' => 50 ] );
if ( null === $leads ) {
    echo esc_html__( 'Feed request logging is off, so there is no win-back list.', 'my-addon' );
} else {
    foreach ( $leads as $lead ) {
        $user = get_userdata( $lead['user_id'] );
        printf(
            '<li>%s — %s, last seen %s</li>',
            esc_html( $user ? $user->display_name : '' ),
            esc_html( $lead['app'] ),
            esc_html( wp_date( 'j M Y', strtotime( $lead['last_polled_at'] . ' UTC' ) ) )
        );
    }
}

Hooks Fired

Notes

There is no capability check, and the rows name people. Check manage_options, or your own capability, before showing them.

null means logging is off, not "nobody". Say so on screen rather than showing an empty list.

The feed request log keeps only its retention window, so a days larger than that returns nothing older. Pass days only when you mean a different window from the Subscribers screen's, and say so on screen.

The app value is named by the same rules as the download charts, so the benecaster_download_app_patterns filter changes both. Every datetime is UTC: convert it with wp_date() for display. See Read Benecaster's analytics numbers instead of copying its SQL.

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