Skip to main content

Read or set an episode’s sponsors, the campaign each is tied to, and their ad positions from code, as the episode editor’s Sponsors tab does

Premium Intermediate Sponsor Manager

The route behind the episode editor’s Sponsors tab: /benecaster-sponsor-manager/v1/shows/{show_id}/episodes/{episode_id}/sponsors. It is admin only (manage_options plus the X-WP-Nonce header). A show where Sponsor Manager is off is refused with 403 benecaster_sponsor_manager_not_active. An episode that is not that show’s, or is trashed, an auto-draft or a revision, is 404 benecaster_sponsor_manager_episode_not_found.

Each sponsor on an episode is tied to one of its campaigns on the episode’s show, or to none (campaign_id 0). A sponsor is a show’s sponsor by having a campaign there (see Read, create, change, archive or restore the site’s sponsors and a show’s sponsor campaigns from code).

  • The episode’s date picks the campaign a newly added sponsor starts on: its publish date if published, its scheduled date if scheduled, a draft’s own date if it has one, and today (site time zone) for a draft with no date and for a new episode. It only sets the default.

  • GET answers 200 { episode_date, items, available }. episode_date is that date, YYYY-MM-DD.

    • items is the episode’s sponsors in order, each { sponsor_id, company, positions, archived, campaign_status, campaign_id, campaign, outside, campaigns }. positions is a list of pre_roll, mid_roll, post_roll, in that order. campaign is the tied campaign as a choice (below), or null for none. outside is true when no offered campaign of the sponsor covers the episode’s date; the tab then warns Outside every {Sponsor} campaign on this show. campaigns is what the tie may be switched to: the sponsor’s active campaigns on the show, plus the tied one if it is archived.
    • available is the active sponsors with an active campaign on the show, company A–Z, each { id, company, campaign_status, campaigns, default_campaign_id, outside }. default_campaign_id is the campaign covering the episode’s date when exactly one does, 0 when none does, and null when several do (the caller must choose).
    • A choice is { id, name, start_date, end_date, status, archived, covers }, newest start first. covers says whether it covers the episode’s date.
    • campaign_status is the sponsor’s standing on this show across its campaigns there.
    • Nothing here carries a contact or a rate.
  • GET /shows/{show_id}/episodes/new/sponsors gives the same answer for an episode not saved yet: items is [] and campaigns are chosen as of today. The same 403 applies.

  • PUT takes { sponsors: [ { sponsor_id, campaign_id, positions: [ … ] }, … ] }, the episode’s whole list in order. A campaign_id of 0, or none, is no campaign, and [] removes every sponsor. It answers like GET. Changing only a campaign is a change. The request is refused whole with 400 benecaster_sponsor_manager_invalid_assignment, data.index naming the entry at fault, for:

    • a list that is not a list, or has more than 50 entries
    • a sponsor listed twice
    • a sponsor with no campaign on the path’s show
    • an archived sponsor, or one whose campaigns on the show are all archived, that the episode does not already have (one it already has may stay)
    • a campaign_id that is not a whole number, or not one of that sponsor’s campaigns on the path’s show
    • an archived campaign the assignment is not already tied to (one it already holds may stay)
    • no position, or a position that is not one of the three

    A write the database refuses is 500. An episode outside every campaign is not refused. Sending the list already stored writes nothing and fires no hook.

  • Hooks: benecaster_sponsor_manager_before_save_episode_sponsors and benecaster_sponsor_manager_after_save_episode_sponsors, both ( int $episode_id, int $show_id, array $sponsors, array $previous ), each list [ [ 'sponsor_id' => int, 'campaign_id' => int, 'positions' => string[] ], … ] in order. The after hook fires only when the write succeeded.

  • When an episode moves to another show, both hooks fire too. Each sponsor with an active campaign on the destination show covering the episode’s date is kept and re-pointed to that campaign (the newest-starting when several do); every other sponsor is dropped. $show_id is then the show the episode moved to, $sponsors the kept list with its new campaign_ids ([] when none is kept), and $previous the list before the move. This happens with Sponsor Manager off on every show too. Deleting an episode for good removes its sponsors with no hook; trashing keeps them.

  • A new episode has no id until Benecaster’s first save. The tab reads …/episodes/new/sponsors, holds the choice, campaign included, in the browser, and sends the PUT when Benecaster dispatches benecaster:episode-created (see Attach your add-on’s work to a new episode once it has been saved). Code that assigns sponsors itself does the same, or waits for benecaster_episode_created. The held campaign is saved as chosen, even if the first save gives the episode a date that campaign does not cover.

Read assignments through this route, or benecaster_sponsor_manager_get_episode_sponsors(), never from the table.

Code

<?php
// Tell an ad-ops sheet whenever an episode's sponsor line-up or campaigns change.
add_action( 'benecaster_sponsor_manager_after_save_episode_sponsors', function ( int $episode_id, int $show_id, array $sponsors, array $previous ): void {
    $before = array_column( $previous, 'campaign_id', 'sponsor_id' );
    foreach ( $sponsors as $entry ) {
        if ( ( $before[ $entry['sponsor_id'] ] ?? null ) !== $entry['campaign_id'] ) {
            my_adops_log( $show_id, $episode_id, $entry['sponsor_id'], $entry['campaign_id'] );
        }
    }
}, 10, 4 );

View on GitHub →

Hooks Used

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