Update to Commanders Act version 5

[defagos]

As a member of the analytics team I want results to be gathered with the new Commanders Act platform requiring version 5 of the SDKs to be running in mobile applications.

Acceptance criteria

• The Commanders Act SDK has been updated.
• Integration documentation has been updated if needed.
• The SDK is available on GitHub.
• Integrators have been notified about the change and the deadline.

Remark: Server-side tags need to be migrated as well for the whole integration to work. Handled by the GD.

Hints

• Migration to V5 is documented. In particular the events are now not anonymous data dictionaries but are specifically defined with their associated data.
• The list of available events is documented.

Tasks

• Update SDK.
• Gather examples to be able to discuss how each use case we support (page view, hidden event, streaming event) must be sent with v5.
• Ask for source key to use.
• Update instantiation.
• Update request interceptor.
• Update hidden event implementation.
• Update API to use "event" term for general events, instead of "hidden event".
• Update page view implementation.
• Update stream tracking implementation.
• Profile app launch time.
• Update integration documentation.
• Replace references to Tag Commander with Commanders Act.
• Remove prod / preprod environment flag. Callers must provide source keys for debug / production instead (and pick the correct one at initialization time).
• Use debug key in SRG Analytics demo.
• Build and send fields which were previously built server-side, e.g. page_unique_name (if the feature is not provided by the new Commanders Act platform). All was migrated in Server side V2 in Data cleansing feature.
• Generate test data for Commanders Act (Play app with v5) sent to debug source keys.
• If SRG SSR debug / production source keys are known to be fixed provide constants for them.
• Related to TCCore 5.x versions, update documentation to provide information about NSBluetoothPeripheralUsageDescription and NSBluetoothAlwaysUsageDescription keys in application Info.plist. Example: "The application should not use Bluetooth. Please don’t allow.".
• Archive SRGSSR "Tag Commander" repositories.
• Update to version 5.3.1 and figure out that a new name for the event title, event_title, conflicting with the reserved event_name from the SDK.
• Update to version 5.3.1 and use now event_name as custom event name, installed of hidden_events.
• Have a look at potential related decisions.
• Clarify pageType and pageName, regarding srg content_title and content_page_type properties.
• Clarify rules client side and server side to split media events and events: SRGAnalytics unit tests don't sent the media_urn, which seems to be the the "media uid" for Webtrekk to group events together. Did in the migration guide.
• Write a migration guide: In wiki part: migration guide.
• Update migration guide with release number and remove "WIP".
• Use iOS debug source key for unit tests.

[defagos]

Some questions to Commanders Act:

About the initialization

• Where can the source key be found in our case?
• Will we need one source key per app or will each BU (or maybe the entire SRG SSR) only need one key for all apps?

Answers for Commanders Act

• The source key is provided once you add a given source into the UI. E.g. if you add an SDK as a source, you will be provided with the source key in the source's settings.
• You will get your statistics and monitoring "per source key", so to say. In general, it makes sense to have one source key per account. It does depend on how you want to organise things on your end, however.

General questions

• Looking at the Android implementation it seems that any custom event parameter set might accidentally override existing official parameters like event_name, for example. This is something that was possible with version 4 of the SDK but can you confirm this is intended v5 behavior as well?
• We assume that the same answer holds for the iOS / tvOS SDK. Correct?

Answers for Commanders Act

• It is the case. Custom properties when named the same as native properties will overwrite their counterpart.
• Yes.

Page views

We have looked at TCPageViewEvent and we think it should match our needs for page view measurements, as follows:

• The page titles are sent under the content_title key with v4 and are technical non-localized page identifiers (e.g. home or player). We therefore think we should send them in page_type with v5. Is it a good idea?
• We are currently not sending any pretty page title, thus we think we should leave page_name empty. Correct?
• We are currently sending other values under other keys and we will send them to v5 in the same way. Some of them are currently processed server-side (e.g. navigation levels which are concatenated together to produce a new identifier) and we assume these rules will be migrated to the new platform as is. Correct?

Answers for Commanders Act

• Yes, I would agree with that.
• Yes, correct.
• It's not possible for now, this will be done with data cleansing and should be available as a first version near the end of the month.

Hidden events

Hidden events are any kind of other tracked events we are currently sending (e.g. the user clicked on some button related to some feature). For those we think we should use TCCustomEvent:

• The event_name should be set to hidden_event. Is it a good idea?
• We are currently sending other values but the keys we are using conflict with official Commanders Act SDK keys (e.g. event_name and event_id). For those we probably need new keys (e.g. hidden_event_name and hidden_event_id) and it is likely that the mapping to Mapp will need to be updated accordingly. Alternatively, we could use page_type to convey the event name (e.g. favorite_add for a tracked button used to add some item to user favorites) instead of introducing a custom parameter name. Which approach would be preferable?

Answers for Commanders Act

• You can name it however you want. Whatever best describes the event.
• Either would work, but the most readable way to handle this would be creating the additional properties in the payload. e.g. hidden_event_name: "favourite_add".
• Depending on what you do with these "hidden_events" and how much data is associated with them, you might want to have an entire custom event dedicated to each. E.g event_name : favorite_add. Would that make sense for you?

Streaming events

For those we think we should use TCCustomEvent:

• The kind of streaming event (e.g. play, pause, etc.) could be sent in event_name. Is it a good idea?
• The rest of the values would be sent in other parameters, as we do today.

Answers for Commanders Act

• It is a good idea. It makes sense to track these as events.
• Thats fine. Wherever we dont provide an event or parameter, a custom one can be created

[defagos]

We'll define a production / test source key pair for the SRG account, which must be supplied when configuring the tracker. These can be then retrieved from the source settings in Commanders Act web interface.

[defagos]

I had a look at our tracker configuration to see whether we could hide the source key internally (release / test), but I am not sure this is a good idea. The API is namely already complicated enough (we have prod / preprod flag, source keys are not known for some BUs yet, and we also have a unit test flag).

I am also not sure having a test source key built with SRG Analytics would be helpful (except for us during the initial validation). So adding it would only add confusion IMHO.

If we obtain one key per BU we could harcode them but otherwise we should likely still ask them at startup time. This is similar to what we were doing with the container until now anyway.

[defagos]

I had to avoid using __attribute__((constructor)) in unit tests since the new Commander Act SDK would otherwise deadlock if initialized from such a function.

[defagos]

As discussed with Commanders Act we currently filter and map some fields server-side (e.g. page_unique_name or fields which are nullable). This feature is not available yet but might be delivered next month. If missing we must be prepared to implement some logic client-side.