kontent-ai/java-packages

SDK tracking header

petrsvihlik opened this issue · 3 comments

petrsvihlik commented

Motivation:
We'd like to start sending a header for identifying SDKs + their versions with each request from all SDKs. The header would be then tracked by App Insights and should provide us with information valuable for multiple departments in Kentico. App Insights already gather information about the user agent, but that is not always usable or present (there are some screenshots below).

In the future, the tracking should help us:

  • identify trends and make decisions regarding future SDK development like:
    • avoid breaking changes (in APIs that are highly used)
    • identify new SDK opportunities (e.g. we may see that users are making plain calls from a certain platform while not using any SDK)
    • new functionality opportunities (similarly to SDK opportunities, we may discovery that certain part of the API is not covered by SDK)
  • discover misbehavior of certain SDK versions
    • see whether users are using the latest version or if they are stuck
  • send out targeted messages about an SDK version being deprecated
  • save round-trips to customer asking about platform they're using and the SDK version (Support)

Specification:
Send the following header with each request to the Kentico Cloud Delivery API.

  • Header name: X-KC-SDKID
  • Header format: ;;
    • PackageRepositoryHost - HOST part of the package repository URI. The value can be hardcoded.
    • SDKPackageID - ID specific for the package repository. In other words, the identifier that's used when specifying the package as a dependency of the resulting application (typically in a json or xml file - package.json, *.csproj, composer.json, etc.) Sometimes the ID can consist of a vendor name and package name. The value can be hardcoded.
    • SDKVersion - version of the package (typically in a semantic version format). This information needs to be either retrieved programmatically during the runtime or hardcoded and manually updated with every release.

Examples:

X-KC-SDKID: nuget.org;KenticoCloud.Delivery;4.12.0
X-KC-SDKID: packagist.org;kentico-cloud/delivery-sdk-php;0.9.1
X-KC-SDKID: maven.org;com.kenticocloud:delivery-sdk-java;1.0.5
X-KC-SDKID: npmjs.com;kentico-cloud-delivery-typescript-sdk;2.2.2
adityasrini commented

Would love to contribute if there aren’t folks already working on this.

petrsvihlik commented

hi @adityasrini, thanks for your interest! let's wait for what @aweigold has to say to this.

hey @aweigold, have you already started working on this one? If not, could you perhaps guide @adityasrini through the process? Thank you!

aweigold commented

Hi @petrsvihlik and @adityasrini , sorry, I didn't see the interest commented here... I had already had this work complete.