Navigation

Navigate within the AppEngine and send Intents from one app to another.

@dynatrace-sdk/navigation

v1.0.2

npm install @dynatrace-sdk/navigation

Interfaces

Intent

Intent accessor API for retrieving received intent.

Use it to retrieve the intent payload passed from the source app and the intent id selected by the user.

Methods

getId

getId(): string

Retrieves the intent id selected by the user.

It is passed via the intent handling route (/intent/:intentId).

Returns

intent id

getPayload

getPayload(): IntentPayload

Retrieves the intent payload object that was passed from the source app.

It contains only these properties that are declared in the app manifest (or dtp.config.ts if you're using @dynatrace/dtp-cli).

Returns

Intent payload

getProperty

getProperty(propertyName): any

Retrieves value of a given property name from the intent payload.

Parameters

Name	Type
propertyName*required	string

IntentPayload

Set of properties that could be passed between apps.

Note: The intent payload contains one or more properties. The properties may be a resource-like (i.e., dt.entity, dt.query) and may define an additional context (i.e., chosen timeframe, associated problem) Intents mechanism is the essential part of the platform navigation. It allows to pass the user flow from one app to another and provides the way to plug different apps into these flows, making the platform open and extendable. Use to pass the intent payload to the platform. Use to handle intents in your app.

PathChangeRequest

Path change request object with a new path.

Properties

Name	Type
path*required	string
pathWithoutBasePath*required	string

Functions

getAppLink

getAppLink(appId,pageToken?): string

Generates a link that launches the specified app on current environment, with an optional internal route specified by pageToken

Note: There is no guarantee that the specified app will be launched since different sets of apps could be installed on different platform instances. Relying on explicitly hardcoded app could lead to broken UX.

Note: a page token is not a URL of the page or a route in the app. It is a dedicated part of the app manifest and considered as an external public API of the app that should be explicitly defined by the app developer. If you're using@dynatrace/dtp-cli, it could be configured in dtp.config.ts.

Parameters

Name	Type	Description
appId*required	string	ID of the app that will be launched.
pageToken	string	Id of the static path segment defining an internal route in app. Warning: not the same thing as URL or route.

Returns

URL to the specified app on current environment.

getIntent

getIntent(): Intent | null

Retrieves the intent data passed to the app.

getIntent method should be used only if the current app route is the intent handling route (/intent/:intentId). Otherwise, it returns null.

Note: The intent is passed to the destination app via the intent handling route (/intent/:intentId). If the app has routing already configured, a new route for handling intents must be declared. Otherwise, it won't be possible to retrieve the intent. If the app has no routing at all, it's not required to configure it. To let the platform know the list of intents your app can handle, you need to declare them in the app manifest (or dtp.config.ts if you're using @dynatrace/dtp-cli).

Returns

Intent accessor, including definition of desired action (intent id) and its payload.

getIntentLink

getIntentLink(intentPayload): string

Generates a link that launches the App Shell on current environment and lets it handle the specified intent.

Note: There is no guarantee that the specified app will be launched since different sets of apps could be installed on different platform instances. Relying on explicitly hardcoded app could lead to broken UX.

Parameters

Name	Type	Description
intentPayload*required	IntentPayload	Set of properties to pass to the platform.

Returns

URL to the specified intent on current environment.

getIntentLink(intentPayload,appId?,intentId?): string

Generates a link that launches the specified app on current environment and lets it handle the specified intent of given id.

Note: There is no guarantee that the specified app will be launched since different sets of apps could be installed on different platform instances. Relying on explicitly hardcoded app could lead to broken UX.

Parameters

Name	Type	Description
intentPayload*required	IntentPayload	Set of properties to pass to the specified app.
appId	string	ID of the app that will be launched to handle the intent.
intentId	string	ID of the action that will be passed to the app.

Returns

URL to the specified intent on current environment.

openApp

openApp(appId,pageToken?): void

Navigates user to the specified app, or its internal route if the pageToken is specified.

Note: a page token is not a URL of the page or a route in the app. It is a dedicated part of the app manifest and considered as an external public API of the app that should be explicitly defined by the app developer. If you're using@dynatrace/dtp-cli, it could be configured in dtp.config.ts.

Note: there is no guarantee that the specified app exists since different sets of apps could be installed on different platform instances. Relying on explicitly hardcoded app could lead to broken UX.

Parameters

Name	Type	Description
appId*required	string	ID of the app that will be launched.
pageToken	string	Id of the static path segment defining an internal route in app. Warning: not the same thing as URL or route.

sendIntent

sendIntent(intentPayload): void

Passes the specified IntentPayload to the Dynatrace platform, which then gets forwarded to the destination app selected by the user.

Note: The list of possible actions and destination apps includes only these actions/apps whose intent declarations are matched against the intent payload. The matching checks whether the payload contains all the properties required in the intent declaration and whether the properties have the correct types. All the undeclared properties are removed from the intent payload when passing it to the destination app.

Parameters

Name	Type	Description
intentPayload*required	IntentPayload	an intent payload object to pass, it may include one or more properties

sendIntent(intentPayload,recommendedAppId?,recommendedIntentId?): void

Passes the specified IntentPayload to the specified app and lets it handle the specified intent of given id. If the specified app does not exist or the specified intent payload does not match, Dynatrace platform handles the intent as if regular sendIntent(intentPayload: IntentPayload) is used.

Note: There is no guarantee that the specified app will be launched since different sets of apps could be installed on different platform instances. And even if the app is installed, its version may not be capable of handling the specified intent payload.

Parameters

Name	Type	Description
intentPayload*required	IntentPayload	an intent payload object to pass, it may include one or more properties
recommendedAppId	string	ID of the app that will be launched to handle the intent.
recommendedIntentId	string	ID of the action that will be passed to the app.

setPathChangeHandler

setPathChangeHandler(handler): void

Registers a custom handler for changing the app's URL path. It is used only for the changes that are triggered externally, outside the app.

If a custom handler is not set, the application is reloaded by replacing the current document location with a new path.

Parameters

Name	Type	Description
handler*required	PathChangeHandler	Custom handler for changing the app's URL path.