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

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