Document Analytics Events for various Prebid systems

[muuki88]

Prebid is about transparency. This is provided to a large extend by the many event/analytics systems built into all prebid products (prebid.js, prebid server, prebid mobile, ... ).

There's a lack of documentation and standardization, which makes it hard to

1. Build analytics systems (for vendors and publishers alike) that work cross product - events from pbjs can be ingested identical to pbs
2. Use events for runtime behaviour, e.g. blocking/filtering/prioritizing

Current status

For prebid.js there is some prebid.js events documention. It's missing type information completely. It also must be kept up to date with constants.json

prebid-server-java defines a range of event classes that are not documented yet.

prebid-server-java defines a similar set of events that can be used by analytics adapter.

Generic Analytic Modules

• Prebid Server Go: Generic Analytics Adapter prebid-server#3388 plus the initial PR that started this HTTP Analytics Module prebid-server#3299
• Prebid.js: https://docs.prebid.org/dev-docs/modules/genericAnalyticsAdapter.html implemented in Generic Analytics Adapter: initial release Prebid.js#9134

Proposal

The first step would be to document the current status on docs.prebid.org.
For prebid-server(-java) this is easy as there are types available. prebid.js is untyped and thus requires a lot more work to find out all possible values.

The question is if we create a new analytics section in the docs for this to aggregate everything, which can be referenced from the different prebid products.

Next step would be to work towards a common events protocol that can be implemented by any third party.

[GLStephen]

I would suggest that code as documentation here would be most valuable. Whether that means formalizing some of the "objects" or events and their end state or some similar techniques I'm not 100% sure. Keeping docs and code synced is the primary challenge of the goal of better transparency here, not the one-time effort to generate the initial docs.

[muuki88]

Keeping docs and code synced is the primary challenge of the goal of better transparency here, not the one-time effort to generate the initial docs

I agree. This is the main challenge for all documentation in prebid currently. While I would love to generate docs from type definition, this is not yet possible 😞 . If we go down the road defining a spec for analytics events, then this would be a different thing as the docs/spec is the source of truth and implementations need to follow. I'm very aware that this is a huge undertaking, but I think it could be worthwhile.

[pm-harshad-mane]

One suggestion, in documentation the events can be listed in the order they occur.