AnalyticsCrossProduct

Utilities to enable cross-product interaction session tracking

This repository is the public facing version of @atlassiansox/analytics-cross-product-interaction-client. Functionality has been duplicated from the private package to enable @atlaskit components to use our library, with the eventual goal of deprecating these functions in the existing package to avoid code duplication.

The functions in this library are designed to work in conjunction with analytics-web-client and analytics-cross-product-interaction-client on Atlassian products, and using these functions on their own will return a no-op.

Overview

The Analytics Web Client generates interaction session data and stores it in Session Storage. The data is in the following shape:

"interactionSession": {
    "id": "123456789",
    "prevId": "912345678",
    "bridge": "atlassianSwitcher",
    "source": "jira"
}

This package exposes: useCrossProductUrlWrapper, a React hook that can be used to retrieve interaction session data and append them as URL parameters onto cross-product navigation URLs

Stream 3 observation contracts

The package also exposes transport-independent building blocks for observing cross-product navigation without adding or changing XPIS:

• xpcDestinationResolver provides controlled product, sub-product, route-family and matcher values plus four-outcome destination resolution: same, cross, unknown and excluded.
• xpcNavigationObservation inspects XPIS presence and builds fresh, privacy-safe departure and arrival observations.
• xpcActivationCoordinator ensures that native and owned final-sink observers complete a user activation at most once.
• xpcNativeDepartureCapture installs delegated click and auxclick capture at a product-owned root while yielding to intercepted renderer sinks.
• xpcFinalSinkDepartureCapture records authoritative renderer handoffs with controlled capture and navigation enums. The schema retains bounded imperative and router values for later, independently gated integrations.
• xpcArrivalCapture inspects an arrival URL locally and reports only XPIS-bearing destination evidence; the URL never enters the observation.
• xpcNavigationProvider composes one product-root native observer, initial-arrival capture, shared activation coordination and renderer final-sink hooks from a product's controlled configuration.
• xpcAwcNavigationReporter is the candidate boundary to a product's existing Analytics Web Client. It deliberately omits the interaction-session ID until its production privacy treatment is approved.

Products supply their own controlled registry entries, source identity, rollout gate and reporter. The shared package does not register a GASv3 event. Product adapters may use the feature-gated candidate Analytics Web Client reporter for validation, but it must remain disabled until the event schema, channel, privacy controls and ownership are approved. Candidate code is not evidence that the event is registered or production-enabled.

Usage within an Atlassian bridge

A bridge is a component that provides a link/navigation to a different Atlassian page, for example:

return <Link href="https://hello.atlassian.net/wiki"> Confluence </Link>

To embed the interaction session properties into the link as a UTM parameter, call our hook useCrossProductUrlWrapper which generates a function to wrap the link with.

Then replace any instances of URLs with the URL wrapped in the hook

import { useCrossProductUrlWrapper }  from '@atlaskit/analytics-cross-product';

const withInteractionSession = useCrossProductUrlWrapper({
    bridge: 'Bridge Name', // The name of your bridge component e.g. atlassianSwitcher
    product: 'Product Name', // The product you are hosted on e.g. jira
    subProduct: 'SubProduct Name', // Optional - include if required
});

return (
    <Link href={withInteractionSession("https://hello.atlassian.net/wiki")}> Confluence </Link>
)

The useCrossProductUrlWrapper hook takes in options of type CrossProductUrlOptions which can be imported from our library if required

The returned wrapper function (withInteractionSession in the above example) takes a URL as a string, and returns a string as well. The return value of the above call would be something like:

https://hello.atlassian.net/wiki?xpis=e2JyaWRnZToiQnJpZGdlIE5hbWUiLGlkOiIxMjM0NTY3ODkiLHNvdXJjZToiUHJvZHVjdCBOYW1lLVN1YlByb2R1Y3QgTmFtZSJ9

with the interaction session data encoded in the ?xpis query parameter (cross-product interaction session)

See our example. To run the example locally:

yarn start @atlaskit/analytics-cross-product

Parameter generation and re-generation

Interaction session data will only be appended to the URL if it has already been generated by the Analytics Web Client and exists in Session Storage. If interaction session data cannot be found, the hook will not modify the URL. The hook is subscribed to a DOM event that will trigger a re-render if a new interaciton session is generated, and will dynamically update the URL to include the correct parameters

Relative URLs

The wrapper supports relative URLs, for example:

withInteractionSession("/wiki")

will return

"/wiki?xpis=e2Jya..."

We use the URL class to perform operations. Note:

• The URL must not have a trailing slash (i.e. use /wiki instead of /wiki/)
• A leading slash will be added to the return output (i.e. wiki will become /wiki?xpis=...)
• Existing query parameters will be preserved (/wiki?a=b becomes /wiki?a=b&xpis=e2Jya...)

Usage with Identity

When a link is wrapped in Identity (passed as the continue paramater in the redirect), Identity encodes query parameters using percent encoding (i.e. &key=value becomes %26key%3Dvalue).

Ensure that our wrapper is called on the href before passing into identity. This will ensure our query parameters are also correctly percent encoded, and will persist after Identity redirect