# @atlaskit/analytics-cross-product

> Utilities to enable cross-product interaction session tracking

Latest version **2.3.1** (published 2026-10-22) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @atlaskit/analytics-cross-product
pnpm add @atlaskit/analytics-cross-product
yarn add @atlaskit/analytics-cross-product
bun add @atlaskit/analytics-cross-product
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.3.1 |
| Published | 2026-10-22 |
| First published | 2026-05-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 181.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian Pty Ltd |
| Maintainers | atlassianartifactteam |

## Links

- npm: https://www.npmjs.com/package/@atlaskit/analytics-cross-product
- Repository: https://bitbucket.org/atlassian/atlassian-frontend-monorepo
- Homepage: https://bitbucket.org/atlassian/atlassian-frontend-monorepo#readme
- Issues: https://bitbucket.org/atlassian/atlassian-frontend-monorepo/issues
- npm.io page: https://npm.io/package/@atlaskit/analytics-cross-product

## Dependencies (5)

- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0
- [@compiled/react](https://npm.io/package/@compiled/react.md) ^1.0.2
- [bind-event-listener](https://npm.io/package/bind-event-listener.md) ^3.0.0
- [@atlaskit/platform-feature-flags](https://npm.io/package/@atlaskit/platform-feature-flags.md) ^2.2.0
- [@atlaskit/platform-feature-experiments](https://npm.io/package/@atlaskit/platform-feature-experiments.md) ^0.3.0

## Recent versions

- 2.3.1 (latest) — 2026-10-22
- 2.3.0 — 2026-10-19
- 2.2.0 — 2026-09-10
- 2.1.1 — 2026-07-21
- 2.1.0 — 2026-07-07
- 2.0.0 — 2026-06-16
- 1.2.0 — 2026-05-25
- 1.1.0 — 2026-05-20
- 1.0.1 — 2026-05-13
- 1.0.0 — 2026-05-11

## README

# 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:

```Json
"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:

```TypeScript
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

```TypeScript
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](./examples/basic.tsx). To run the example locally:

```bash
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:

```TypeScript
withInteractionSession("/wiki")
```

will return

```TypeScript
"/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

---
_Source: https://npm.io/package/@atlaskit/analytics-cross-product · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
