prebid / prebid.github.io

Repo that controls Prebid.org website
http://prebid.org
Apache License 2.0
69 stars 1.19k forks source link

Document Analytics Events for various Prebid systems #5073

Open muuki88 opened 10 months ago

muuki88 commented 10 months ago

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

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 commented 10 months ago

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 commented 10 months ago

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 :disappointed: . 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 commented 8 months ago

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