Proposal: <podcast:events> tag, enabling podcast publishers to receive unforgeable inbound events from other entities in the open podcast ecosystem

[johnspurlock]

I've been listening and thinking about several conversations in the podcast world recently, and I think it would great if we could come up with a solid way of letting podcasters receive inbound events from verifiable 3rd party actors (podcast apps, directories, other hosts) with useful information for them. For example, a way for trusted podcast apps to send unforgeable information about subscribers/play information back to the show.

Ideally, we could do this in a way similar to the other podcast namespace tags, that kept the podcast feed publisher in control, and as the source of truth, while keeping things as simple as possible and without needing preauthorization or shared secrets, or certifications, etc.

Instead of a wall of markdown here in the github issue, I've started a quick Google doc with the general overview of a system I think could work well, and am publishing it publicly to see what everyone thinks and get the conversation started:

[Google Doc] Proposal: <podcast:events> tag, enabling podcast publishers to receive unforgeable inbound events from other entities in the open podcast ecosystem

It's meant to be readable by anyone, so I tried to avoid rabbit-holing on a bunch of detailed example code, but there should be enough in there for folks to get the idea.

2022-10-06: Published a new skymethod/podcast-events GitHub repo with a full implementation of both the sending side and the receiving side. Also a validator to test client implementations at: https://podcast-events-validator.op3.dev/. Both linked in the proposal doc

2022-10-22: Added a new "Event batching" section about how to reduce the number of calls required to the same receiver (e.g. the same podcast hosting company) by sending events for multiple feeds in the same payload

[theDanielJLewis]

I foresee some feet-dragging for app-developers to support this, but I do really like the idea and see a ton of potential for it!

I have a few thoughts for potential improvement.

1. I suggest making it <podcast:webhook> instead of <podcast:events>. I think "webhook" communicates its purpose better, avoids potential confusion, and leaves the "events" word usable for other plain-English uses (like a way for a podcaster to indicate layman "events," like a meetup, a live-stream, etc.). And before anyone says, "It doesn't matter what we call it, and only developers will see it," I think it does matter what we call it because podcasters need to be able to easily understand it, ask their publishing tools about it, and for it to be easy to educate them.
2. Your example showed this in <channel>. I think there could be some uses for putting it in <item> tags, too.
3. For any kind of episode event, I think we should send the item GUID instead of the enclosure URL because the GUID is supposed to never change for an episode, but enclosure URLs can change at any time.

I could see such a webhook receiving all kinds of information (not necessarily that these are the best ways to send such information, but this is only for brainstorming), whenever:

• someone follows or unfollows the show,
• someone comments on an episode,
• someone shares an episode,
• someone deletes an episode without finishing it,
• the podcast is featured in the app catalog,
• the podcast receives a rating or review,
• the podcast's catalog listing is visited from an in-app ad (paired with when someone follows a show, this can provide great conversion data!)

[samsethi]

As an app developer, I need to be convinced why I should share this user data for free to other entities. This activity data is my competitive advantage.

[redimongo]

@samsethi - am a little late to this conversation, but your sharing it to the podcast creator, I am assuming as this is data that they need and should have. Also it allows them to promote your app if you share this with their podcast hosting provider - even if they self host.

[samsethi]

Once a podcaster claims their podcast on TrueFans they get access to an admin dashboard to see an individual/aggregated view of their fan's activity. i.e who played each episode, how long (listen time), percent completed and value paid (if any in SATs). You can then sort this by who played or paid the most etc. We also show various aggregated charts with drill downs.

The individual fan can choose in their settings what verbs/activities they will display or hide on their profile. We are adding an option for fans to publish these verbs via our ActivityPub Server or to a known Social Interact Tag endpoint.

We will build a mechanism for podcasters to sell their aggregated activity data to hosts but TrueFans won't give this data to hosts for free. So if a host wants to get this data they can offer podcasters SATs or reduced hosting costs? The podcaster can then choose to share this payment with their fans. Equally fans can choose not to share the data with the podcaster. It's all about V4V and privacy.

[redimongo]

@samsethi What if say a podcaster self hosts, do you charge them to get access to their own data? This data at the end of the day should belong to the podcast creator, I understand you have to make money. But the idea of an "open" eco system is one where the podcaster is in control of the content & data and can do as they please.

Shouldn't any player/platform follow the instructions of what the podcaster creator wants to do with their data?

[samsethi]

The Activity data is 100% the users. They opt-in to share with the creator. They decide what verbs are public and what are private. The creator is free to share the aggregated activity data they receive with anyone i.e their host or their friends on social media etc. I think on this we agree. I do not charge any user for access to THEIR data.

What I object to is hosts assuming that they can get this data for free. Hosts only know about downloads and that is the end of their knowledge. They don't know about listen time, value paid etc That first-party data is only known by apps, the users and podcast creators. This is the dilemma hosts now face. How can they access this valuable data? That is why I say downloads as a metric is legacy data. It has minor value and if we are to really give valuable data back to creators and advertisers then we need to use Activitystream structured JSON-LD data.

I agree a common goal for the whole podcasting 2.0 community is how best can we share this data. Users can choose to share reviews, clips, boosts, ratings, and plays to their social media at NO cost. These are all activity verbs. Additionally, a creator in their RSS feed can set the social interact tag to point to a particular post and users can also share their activity data for an episode to this endpoint. This is how we might get cross-app comments, cross-app ratings etc. Hosts and other apps will need to listen to these social interact endpoints to check for posts from other apps. Hosts can do the same.

For example, if I listen to Podcasting 2.0 with Adam and Dave, they have a link in the social interact tag to a post on AP/Mastodon. As an app, we will help users to share their activity. We will prompt the user if they want to share it to a social interact tag endpoint and/or their own profile post. So if we detect a social interact tag in the RSS feed we will tell users that the creator has asked for comments, ratings etc to be posted here. If we don't, then we will post it to their own profile page. I am not saying we have 100% figured this out but this is my arrow of direction.

However, any hosts hoping to just access all this data freely from apps. That will not happen. Like OP3, creators can choose to opt in and share data with their hosts. Today most apps make no money. Hosts make all the money in the 'open' ecosystem. Maybe hosts will reduce their hosting fees if creators share their first-party activity data with them? i.e V4V

Our goal is to charge creators for additional pro services beyond their basic admin dashboard features and then share the value we earn back with the users as it was their valuable data in the first place.

BTW Today only 5 hosts support the social interact tag. We need more hosts to support this first before we talk about cross-app data being made available and shared with the whole ecosystem.

[jamescridland]

This seems quite close in functionality to NPR's RAD proposal, and I wonder whether it's worth reviewing that for ideas and gotchas of how it was proposed there. Particularly, the opportunity to request the app to "tell me if this point was played" was helpful for program research and potentially for ad delivery.

Improvements on it are the use of signed data, and as @theDanielJLewis says, it could be extensible with a number of different ideas.

I like the webhook name suggestion. Like switching text to txt, I think it's important to use unambiguous language that helps a rookie get up to speed as fast as possible.

I would also suggest it's unlikely to get take-up in apps: unless a) someone pays them to implement it; or b) someone associated with this proposal builds an app that we can get behind

[johnspurlock]

Some differences between this and RAD (spec):

• RAD is primarily designed to report advertising events (see their event properties), this proposal is primarily designed to raise the level of quality listen metrics available to publishers without taking a step back on listener privacy in any way
• It is not helpful to advertisers directly, only in the aggregate sense that publishers will have a better idea how many of their downloads were actually listens, for participating podcast apps
• RAD events can be easily forged, the 'listen' events in this proposal cannot
• RAD events require embedding information into ID3 tags (!), this proposal does not

More context around this proposal: there has been some indications by some of the large podcast apps that they would be willing to send this listen data (which they already collect) securely to publishers in order to help raise the quality bar and prevent overbilling, but will only do it if it does not take a step back on privacy in any way.

The mechanism this proposal uses was specifically chosen to be something that Apple, for example, would be willing to implement - once a consensus is reached on the payload. The auth mechanism (JWT with public JWK url sets) in particular was chosen since it's not only an industry standard these days, but also used by Apple in other callback apis where security is key (Sign-in with Apple / App Store In-app purchase callback notifications), ie their security team has already blessed something similar.

[johnspurlock]

Re: embedding in apps, this proposal is strictly server-to-server, since each request needs to be signed with the private side of the RSA keypair. The private side would never leave the sender's servers or be embedded in a client app or website, etc.

The flow would be that the app sends listen data down to their servers in the same way they do today, then periodically send it server-to-server for feeds that declare <podcast:events>

[daveajones]

After reading through everything, I wonder would this be doable as podping notifications? Same payload, but without the need for JWT since Hive does the authentication and it requires staking. Perhaps you are worried about message volume overwhelming Hive?

[theDanielJLewis]

Bringing up the difference with RAD inspired a thought. This kind of webhook indicator would receive anything the app sends it. But should we consider a way for podcasts to indicate (probably in the episode JSON data) particular triggers? Like ping the webhook if X chapter is completed, or if XX:XX point is played, or if X% is played.

[johnspurlock]

I wonder would this be doable as podping notifications?

The thing is I think we want something that the app sends securely, and targeted only to the show, and the show's declared third parties. Hive would leave the listen data wide open, right?

I guess there would be nothing preventing someone from starting a service that implemented the receiving side of this protocol (something DJ could do in a weekend!), got used by podcasters in their feeds, and turned around and republished that data back out to Hive or anywhere else - but it's the podcaster's choice in this case.

[jamescridland]

Listening to the board meeting with Dave and Adam.

I like the idea of a different example rather than starting with "listens", given the almost instant "but NPR RAD, blah blah" reaction.

One that seems to be a great and simple usecase is "reviews". When I get a review on a podcast in Podverse, send that review back to me using a webhook.

I can absolutely build a receiver for Podnews (it would be super dumb, just capturing the info in a database) if you need a podcast using one.

[johnspurlock]

One that seems to be a great and simple usecase is "reviews"

I like this idea! I'll try to compile a quick summary of all of the great ideas from folks I've heard so far and put them in the doc, and provide ratings payload examples alongside listen info so it doesn't seem so tied to one use case.

Strawman ratings item-level payload(s):

Like all event payloads, fields common to all events can be included once in the top-level object instead of repeated in every item-level payload.

All fields are required except the ones marked optional.

Rating summary

Could be sent daily/weekly if the app doesn't want to send every rating/review.

{
  "kind": "rating-summary",
  "asof": "2022-10-08T16:00:00.000Z",
  "rating": 4.7,
  "ratingScaleMin": 1,
  "ratingScaleMax": 5,
  "count": 955,
  "episodeUrl": "<episode url that was downloaded>", // optional, only for apps that support episode-level reviews
  "feedUrl": "<feed of the subject show in question>",
  "userAgent": "<user agent that downloaded the episode>",
  "referer": "<referer that downloaded the episode>", // optional, only applicable for webapps
}

Rating

For apps willing to send every rating/review.

{
  "kind": "rating",
  "time": "2022-10-08T16:49:00.226Z",
  "rating": 4,
  "ratingScaleMin": 1,
  "ratingScaleMax": 5,
  "review": "Hats off to Jane Doe who excels in character development and tells a great story with brilliant historical context.",
  "author", "JohnDoe",
  "episodeUrl": "<episode url that was downloaded>", // optional, only for apps that support episode-level reviews
  "feedUrl": "<feed of the subject show in question>",
  "userAgent": "<user agent that downloaded the episode>",
  "referer": "<referer that downloaded the episode>", // optional, only applicable for webapps
}

Update: I put these in the google doc

[theDanielJLewis]

Consider what could be done with a tool like Zapier or IFTTT. Both services can offer webhooks for listening. So doing something in the podcast app could trigger a Zapier or IFTTT action.

One (not necessarily recommended) example could be a system to auto-tweet whenever my show gets a new follower, and then promotes my follow page. "Someone from Cincinnati just subscribed to The Audacity to Podcast. Have you? [URL]"

@johnspurlock, I have a ton of thoughts of how to best format rating and review data (since that is literally my business), but we can discuss that later.

[johnspurlock]

The key thing about this proposal is that the requests are signed with strong encryption and need to be verified by the receiver before being processed or forwarded on. It's a way to setup an unforgeable/unspoofable channel from the podcast app -> feed owner (podcaster/podcast hosting company).

So as long as first receiver (the inboxUrl declared in the tag) can do the encryption necessary to verify the signature of the payloads coming in, it would be ok.

I'm thinking that the flow would be that the podcast hosting company (or 3rd party) declared as the inboxUrl in the tag would be the first receiver, trusted to properly verify the events and handle policy around which apps are trusted. Then provide checkboxes/fields in their podcaster-facing CMS for various event hooks like: "rating webhook url", which could then be ifttt/zapier/webhook-co-of-the-month

[theDanielJLewis]

Perhaps there could be a public key, or some simple authentication process, that podcasters could give to various apps, or else there's a central list of approved apps allowed to send payloads to the webhook URL.

For example, Libsyn would already know have the signature stuff in place to authenticate anything from Podverse, Overcast, Apple Podcasts, and such. But for any fringe app or service, the podcaster needs to get a public API key from their hosting provider (or Zapier) that they provide to that app in order to give them permission to send the data. Anything gets block that comes in that's not preapproved by the webhook provider or using a key the podcaster has authorized.

[theDanielJLewis]

Can we please quickly change this to <podcast:webhook> before we go much further?

"Events" is a geeky term, and I believe the intention of RSS was to maintain some level of human readability. But more important than that, I'd like us to reserve the "events" name for a different use, like allowing podcasters to promote actual events (conferences, live-streams, meetups, giveaways, promotions, deadlines, etc.) in their podcasts through a special tag.

I also think we could simplify the tag by changing inboxUrl to simply url. After all, wouldn't any URL we use be an inbox URL? It's fewer characters and more straightforward.

[johnspurlock]

@theDanielJLewis I'm happy to bikeshed the names later, but right now let's keep the documentation/artifacts stable while people are reading it - waiting to get feedback from a wider group of people. One thing to keep in mind is that while the tag only has one attribute today, it might have additional useful properties in the future (like the receiver's verifiable identity etc) so I wouldn't want to limit it to a single url (hence inboxUrl in my proposal).

@samsethi Sending user activities down to the show is a really neat idea. This looks a lot like activitypub, but perhaps this is a quicker way to jumpstart, the publisher could always turn around and resyndicate over activitypub or whatever they like. A big advantage this proposal has over activitypub is that the events are verified to be coming from an app with a strong public identity. So apps have the incentive not to spam, since the receiver can easily decide to drop all incoming events from their app, or events of a certain type.

Would love to brainstorm with you about what the payload for these user activity events would look like. How to identity a user, and keep the actions freeform enough to support verbs not yet considered.

[jamescridland]

Worthwhile linking to this today - a feature that I think podcast:events could help with.

https://wearebumper.com/blog/2023/01/16/listen-time/

I've pointed the author here, too.

[theDanielJLewis]

That reminded me to bring in this prior discussion from a couple years before: #87

[keunes]

User interest: https://twitter.com/ArunangshuGh/status/1660180929040748551

[redimongo]

@johnspurlock I thought I would see if there has been any movement in getting events off the ground? Over the last two days I have coded a test of podcast:performance which @jamescridland said you proposed events a while ago. I think this could fit nicely into events, but I wanted to get a test sample up and working so people could see how it could work.

I have published the server code (I modified the one we use for PodToo and open sourced it) I have taken into account what James said about privacy we HASH the IP address and user-agent so the IP address is not stored, and the data is only sent once when a user switched episode or exits the screen.

Demo can be found at https://codepen.io/redimongo/full/BaeQyaP
Server code and all future code can be found at https://github.com/podtoo/podcast-performance

It can then generate a chart like this

[theDanielJLewis]

And look at #472 and #87, which are similar to this, but I still think should integrated with Activity Stream instead of building something separate. Once apps support podcast Activity Streams for cross-app comments, boostagrams, ratings and reviews, and more, adding consumption reporting is simply an additional ping and verb.

[redimongo]

@theDanielJLewis while I agree with you, we will be waiting awhile for Podcast Apps to integrate Activity Streams as I haven't yet seen one app say that they are doing this - I could be wrong.

As for #472 I have to side on privacy, while yes PodToo does allow our clients to send a UUID or email address with every request, we inform our clients of the risk and safety concerns if talking about topics that are illegal in some countries. I think @jamescridland commented really well on the topic. As for why we did not include that code in our sample GitHub code? It was out of scope of what our goal is and potentially would derail the idea. I have done my best to minimise privacy concerns by publishing the code as we recommend it be used any modifications is on a server level and may not be supported by the community.

As for #87 we could incorporate an extra bit to instruct the player on how much data we want to collect, the code I published was a proof on concept and to get the community talking. I think the correct thing is to let the podcaster choose how much data they want to get back from the player.

As I don't want to mix <podcast:performance> tag up with <podcast:events> until we get some consensus on what the community would support, I'll keep all the discussion for the current code on #639. Also :events tag is a 3 year idea that seemed to have not progressed - I hope I am wrong.

[jamescridland]

I still think should integrated with Activity Stream instead of building something separate. Once apps support podcast Activity Streams for cross-app comments, boostagrams, ratings and reviews, and more, adding consumption reporting is simply an additional ping and verb.

I'd really like to understand this more and how it fits with listener privacy.

There's a big difference between the following:

• A random IP address listens to "My Big Gay Wedding". That IP address is stored by the publisher of "My Big Gay Wedding", but without more work, they can't track that back to a human being.

and

• Joe Bloggs listens to "My Big Gay Wedding", and listens to twenty-five minutes before pausing, listening to something else, then coming back to "My Big Gay Wedding" and continuing listening for fifteen more minutes, skipping past the ad

It seems to me that ActivityStreams puts all of Joe Bloggs's listening habits online, in a big file marked "Joe Bloggs's listening habits", for all to see. OR, perhaps, it's just a big file marked "USER 12463's listening habits", but even so, it's a big data trove of information that can be used to work out that it's really Joe Bloggs.

Where can I go to learn more about the privacy aspects of this?

[johnspurlock]

careful @redimongo you'll want to make sure at a minimum that your solution:

• does not send play data at the user-level or directly from client ips, should be batched/aggregated by your server to preserve privacy
• is unforgeable, for example using a keypair like the events proposal does, otherwise it's trivially gameable - again the solution to this is to send aggregated data collected on your server (where the private key can be protected), not directly from client players

[redimongo]

@johnspurlock

I was going to write a really long response but I have been sitting on this for about an hour re-thinking the code we published. Why, because of this one line in your comment.

is unforgeable, for example using a keypair like the events proposal does, otherwise it's trivially gameable - again the solution to this is to send aggregated data collected on your server (where the private key can be protected), not directly from client players

So first thank you, Yes, I am going to implementing a quick generate session which would add a key to the end of the post URL. Ensuring that the data remains secure and unforgeable - as you can only send data to that key once per EpisodeGUID otherwise if it's still valid it will update the data with the latest data and remove old data. We will also then test the removal of all IP addresses in any header that is sent, which would solve the point about being a client-side privacy issue.

• Old way
  <podcast:performance>https://api.podtoo.com/episodeperformance</podcast:performance>
• New way
  <podcast:performance url='https://api.podtoo.com/episodeperformance/:GeneratedKey' duration='120'></podcast:performance>

Because this is meant to be client side sending the user play time data, it's important that we think about the privacy of all I will tonight also add a duration option which means the podcaster can say they are only interested in every 120 seconds of player data not every second.

If this is of interest to anyone full code is available at https://github.com/podtoo/podcast-performance we will even be switching to this as our main server that collects player data.

We have also today launched https://podcastperformance.com/ and have decided that PodToo will use that server being open and transparent is key.

[redimongo]

Ok, so one of our podcast clients literally messages me today, asking how do we see our ratings.

So I want to go over this by @johnspurlock who has kindly given us some guideline on how to create it.

First the ratings code John suggested.

{
  "kind": "rating",
  "time": "2022-10-08T16:49:00.226Z",
  "rating": 4,
  "ratingScaleMin": 1,
  "ratingScaleMax": 5,
  "review": "Hats off to Jane Doe who excels in character development and tells a great story with brilliant historical context.",
  "author", "JohnDoe",
  "episodeUrl": "<episode url that was downloaded>", // optional, only for apps that support episode-level reviews
  "feedUrl": "<feed of the subject show in question>",
  "userAgent": "<user agent that downloaded the episode>",
  "referer": "<referer that downloaded the episode>", // optional, only applicable for webapps
}

I would like to suggest some changes

{
  "kind": "rating",
  "time": "2022-10-08T16:49:00.226Z",
  "rating": 4,
  "ratingScaleMin": 1,
  "ratingScaleMax": 5,
  "review": "Hats off to Jane Doe who excels in character development and tells a great story with brilliant historical context.", // optional
  "author", "JohnDoe", // could be the podcast player apps username
  "episodeGUID": "<guid tag>", // optional, only for apps that support episode-level reviews
  "feedGUID": "<feed podcast:guid>",
  "userAgent": "<user agent that downloaded the episode>",
  "referer": "<referer that downloaded the episode>", // optional, only applicable for webapps
}

Optional needs discussion: Say Podverse user JohnDoe sent the review above, because we know that the user-agent = podverse we can do a .JSON approach similar to how we check apps.json (https://github.com/opawg/user-agents-v2) we could add a field called user_profiles in user-agent-v2 (or similar) and that could be for example be like https://podverse.fm/user/JohnDoe

Note then podverse could do as they please either show all the reviews by JohnDoe. But also apps don't need to link the username if they don't want. (Again I would say privacy, but I also think we need to acknowledge the platform that sent the review).

This one would work as well, for apps that don't want to send each user review.

{
  "kind": "rating-summary",
  "asof": "2022-10-08T16:00:00.000Z",
  "rating": 4.7,
  "ratingScaleMin": 1,
  "ratingScaleMax": 5,
  "count": 955,
  "episodeGUID": "<guid tag>", // optional, only for apps that support episode-level reviews
  "feedGUID": "<feed podcast:guid>",
  "userAgent": "<user agent that downloaded the episode>",
  "referer": "<referer that downloaded the episode>", // optional, only applicable for webapps
}

[samsethi]

In TrueFans 'Review' is an activity verb as is 'Rating'. I like your new structure for the review which includes the Feed & Item GUID. I would also like to add a time-listened metric to the review. A person who has not listened to the episode will not be allowed to leave a review or rating on TrueFans. Equally, a review has greater value i fI know you listened to at least 50% of my show as opposed to 1%.

Last week we added 'Buy' and 'TopUp' as new Activity Verbs. This month TrueFans will allow all users to export their ActivityStream using this W3C format. https://www.w3.org/TR/activitystreams-core/

We have over 30 activity verbs in TrueFans and will publish those for everyone to share and give feedback.

[redimongo]

@samsethi lets have a Google meeting call. We are both doing the same thing, just going at this a little different. I am trying to do it for an open source version which will allow anyone who creates their own podcast hosting server to do all the things that you do.

Also when you say a person - they don't have to been known as John Doe, as we just use session unless its a review, rating or something where user can POST a message or submit an answer, then for example if the user was coming from TrueFans it would be something like

{author: '[email protected]'}

or

{
author:'[email protected]' // if the user does not want to share their name however they would not be able to fetch the data back unless true fans stored it in their account some how.
}

We both want the same goals here.

[theDanielJLewis]

Small aside (months later): reviews would be best to also include a title, the source app, and source country.