Skip to main content

Track a link that belongs to no show — a guest’s book, a sponsor page — and get its /go/ address

Premium Intermediate Outlinks

A site-wide link is a tracked Outlinks link with no show. Guest Manager’s Track with Outlinks beside a guest’s publication uses one, because a guest is the site’s, not a show’s. It answers at /go/{slug} like any tracked link (names are unique across the whole site), with the same affiliate URL, country rules and expiry, and its clicks are reported on Settings → Site-wide Links, never on a show’s Outlinks tab.

When it is tracked: while Outlinks is switched on for at least one show. A click is then recorded (no personal data), routed by country and affiliate URL, and fires benecaster_outlinks_click_logged and benecaster_outlinks_before_redirect with $episode_id always null, since there is no show to match an episode against. When Outlinks is off for every show, the license has lapsed, or the license server has been out of reach for 30 days, a site-wide link redirects straight to its destination like any show’s link: nothing is recorded, routed or fired.

benecaster_outlinks_site_link( string $url, array $args = [] ) creates or finds the site-wide link for $url:

  • $url is cleaned with esc_url_raw() and must be http or https, else a WP_Error benecaster_outlinks_url_invalid.
  • It finds first. If a site-wide link’s stored destination is exactly the cleaned URL, that link is returned (the oldest when there are several) with created => false, and $args['slug'] is ignored. A show’s tracked link to the same URL is never returned.
  • Otherwise it creates one, with created => true. $args['slug'] is cleaned with sanitize_title() (at most 100 characters); an unusable one is benecaster_outlinks_slug_invalid, a taken one benecaster_outlinks_slug_taken with [ 'suggestion' => string ] as its data. Without slug, Outlinks picks a name from the URL’s last path segment (or its host) and makes it free with -2, -3.
  • It returns [ 'id', 'slug', 'go_url', 'destination_url', 'affiliate_url', 'created' ]. go_url is the address to publish. affiliate_url is null until someone sets one on Settings → Site-wide Links or over REST.

benecaster_outlinks_get_site_link( int $id ) returns the same keys without created, for drawing a link whose id you stored. It returns null for an unknown id and for a show’s tracked link.

Code

<?php
// Guest Manager's "Track with Outlinks", from a handler that checked manage_options.
if ( function_exists( 'benecaster_outlinks_site_link' ) ) {
    $link = benecaster_outlinks_site_link( $publication['url'], [ 'slug' => sanitize_title( $publication['title'] ) ] );
    if ( is_wp_error( $link ) && 'benecaster_outlinks_slug_taken' === $link->get_error_code() ) {
        $link = benecaster_outlinks_site_link( $publication['url'], [ 'slug' => $link->get_error_data()['suggestion'] ] );
    }
    if ( ! is_wp_error( $link ) ) {
        $publication['outlinks_id'] = $link['id'];
    }
}

// On the guest page.
$tracked = ! empty( $publication['outlinks_id'] ) && function_exists( 'benecaster_outlinks_get_site_link' )
    ? benecaster_outlinks_get_site_link( (int) $publication['outlinks_id'] )
    : null;
$href = null !== $tracked ? $tracked['go_url'] : $publication['url'];

View on GitHub →

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