Skip to main content

Read or change a show’s Analytics Dashboard digest settings

Premium Intermediate

Each show has its own digest settings: what the Digest emails screen (#/analytics/settings) reads and saves. Read them before contributing a digest section that only makes sense weekly, say, or to show a show’s digest state in your own screen. Same permission and 403 as the other Analytics Dashboard routes; scope and tier_slug are ignored.

  • send_time is HH:MM in the site’s time zone (timezone is wp_timezone_string()), one time for all three digests. The days a digest reports on are UTC days.
  • threshold is on_change (send the daily digest only when the subscriber count changed) or always. The weekly day is an ISO weekday, 1 = Monday; the monthly day is 1 to 28.
  • recipients are WordPress user IDs, each able to manage_options; recipient_choices is { id, name, email } for every such user. A recipient who loses the capability is dropped on read, and with none left the site admin (the user with the Administration Email Address) is the recipient.
  • POST { show_id, settings } replaces the whole object: every field is required. An invalid one answers 400 benecaster_analytics_digest_invalid with the field in data.field (recipients, monthly.day, …), and nothing is stored. A good one answers as GET does.
  • In PHP the settings live in the option benecaster_analytics_digest_settings, a map of show ID to that object. Read it through the route, not the option: a missing option or field means the default, and the route fills those in. Core’s Reset Plugin Data deletes the option.
  • POST also sets the digest cron (benecaster_analytics_digest_check) again for the new times.
  • Both answer unsubscribed: [ { user_id, type, at } ], each person who left a digest through its email link (at UTC; option benecaster_analytics_digest_unsubscribes). POST analytics/digest/resubscribe { show_id, user_id, type } undoes one and answers as GET does. It is the only way one is undone: ticking the person again, or switching the digest off and on, changes nothing.

Code

const url = window.benecasterAnalyticsDashboard.apiUrl + 'analytics/digest/settings?show_id=12';
const { settings, recipient_choices, timezone } = await ( await fetch( url, { headers: { 'X-WP-Nonce': window.benecasterAdmin.nonce } } ) ).json();
// settings = { paused: false, send_time: '09:00', recipients: [ 1 ],
//   daily: { enabled: false, threshold: 'on_change' }, weekly: { enabled: true, day: 5 }, monthly: { enabled: false, day: 1 } }

View on GitHub →

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