@adobe/exc-app

This project provides the interface for app developers to integrate with the experience cloud unified shell web application at https://experience.adobe.com

Usage no npm install needed!

<script type="module">
  import adobeExcApp from 'https://cdn.skypack.dev/@adobe/exc-app';
</script>

README

exc-app

Adobe Experience Cloud gives you everything you need to bring world-class experiences to every customer. It consists of multiple solutions that power insights, content, engagement, commerce and optimization. The unified shell web application at https://experience.adobe.com provides a unified user experience for customers to manage these solutions from a single place.

The solution experiences run within an iframe in the unified shell web application and can interact with components of the unified shell such as topbar, menus, nps, alerts, etc. These interactions are made possible through two components: -

  1. A module-runtime script that is injected into the product iframe
  2. This @adobe/exc-app package that provides an API to interact with the injected module-runtime script.

Getting Started

To get started with this integration, below two things need to be done.

  1. Include the runtime loader script on the home page
  2. Include the @adobe/exc-app package in your NPM package.json and invoke the init API.
import React from 'react';
import ReactDOM from 'react-dom';
import {init} from '@adobe/exc-app';

init(runtime => {
  // Example initialization for a solution that uses React
  ReactDOM.render(<MyProductPage runtime={runtime} />, document.querySelector('#main'));
});

Features

APIs

root

Core APIs that let solutions initialize the application, provide access to the runtime object from anywhere in the app, listen to events. learn more

AppApi

APIs that provide access to certain data types nested inside the app Context. learn more

HelpCenter

APIs that let solutions interact with the Help Center menu. learn more

Metrics

APIs used to log messages, errors, events, metrics and analytics that get pushed to our telemetry system. learn more

Network

APIs that simplify code to make authenticated network requests for resources, execute GraphQL queries, etc. and optimize them through efficient batching when appropriate. learn more

NPS

APIs that let solutions interact with the NPS (Net Promoter Score) widget component, the interface for recording user experience within a specific solution. learn more

OrgSwitcher

APIs that let solutions interact with Org Switcher menu. learn more

Page

APIs that let solutions interact with the main page and personalize it, e.g. setting the title, favicon, refreshing the solution iframe, etc. learn more

Pulse

APIs that let solutions interact with Pulse, Adobe's Notification System. learn more

Settings

APIs to get or set settings, preferences or configuration data that can be stored and retrieved at an IMS user and/or an IMS org level. An app in unified shell can consume Settings service. learn more

TopBar

APIs that let solutions interact with the top bar and personalize it, e.g. configuring the solution area on the left, setting up workspaces, custom search, etc. learn more

User

APIs to request user-specific information such as IMS organization, IMS profile, access token, tenant, etc. It also provides solutions with other capabilities such as notifying the shell that the session has expired and configuring a logout URL to expire custom sessions. learn more

UserProfile

APIs that let solutions interact with User Profile menu. learn more

Events

Events are emitted by the module runtime when it receives certain messages from the Unified Shell.

Ready

The ready event fires when the initial configuration has been received from the Shell. It would make sense to wait for this event before rendering the application or setting any workspaces. The locale will be required to do globalization and we require the workspaces translated prior to setting them on the Shell, since we don’t (and shouldn’t) have translations for every Solution’s workspaces.

Example:

import excApp from '@adobe/exc-app';

function setup() {
  const runtime = excApp();
  runtime.on('ready', ({imsOrg, imsToken, locale}) => {
  this.setState({
      imsOrg,
      imsToken,
      loading: false,
      locale
  });
  });
}

Payload:

  • baseUrl: Base url for the solution.
  • environment: Environment being used.
  • historyType: Type of history.
  • imsEnvironment: IMS environment. This follows general rules unless shell_ims query param is in use.
  • imsOrg: IMS org ID.
  • imsOrgName: Name of the IMS org.
  • imsProfile: Object containing information about the authenticated user.
  • imsToken: IMS token.
  • locale: Locale string for globalization.
  • preferredLanguages: List of preferred languages from the user's IMS profile.
  • shellInfo: Shell related information needed to populate the shell UI. More details about what is included are Shell API.
  • tenant: tenant name for current ims org.

Configuration

The configuration event fires when any configuration changes from the Shell. This has the same payload as the ready event.

Example:

import runtime from '@adobe/exc-app';

function setup() {
  const runtime = excApp();
  runtime.on('configuration', ({imsOrg, imsToken, locale}) => {
    if (imsOrg !== this.state.imsOrg) {
      // Change org
    }
    this.setState({imsOrg, imsToken, locale});
  });
}

History

The history event fires when the browser history changes and the frame needs to know about it.

Example:

import runtime from '@adobe/exc-app';

function setup() {
  const runtime = excApp();
  runtime.on('history', ({type, path}) => {
    const cleanedPath = path[0] === '/' ? path : '/' + path;
    if (type === 'external' && this.history.location.pathname !== cleanedPath) {
      this.history.replace(cleanedPath);
    }
  });
}

Payload:

  • type: Internal or external depending on where the event originates from.
  • path: The new path to update the browser history with.

Licensing

This project is licensed under the Creative Commons Attribution-NoDerivatives 4.0 International Public License. See LICENSE for more information.

interfaces appapi.appapi-1md

@adobe/exc-app

Globals / appapi / AppApi

Interface: AppApi

Hierarchy

  • AppApi

Index

interfaces-appapiappapi-1md > Methods

Methods

interfaces-appapiappapi-1md > get

get(appId: AppId): Promise<AppResponse>

API to fetch metadata for one app by appId

interfaces-appapiappapi-1md > Parameters:

Name Type
appId AppId

Returns: Promise<AppResponse>

interfaces appapi.appresponsemd

@adobe/exc-app

Globals / appapi / AppResponse

Interface: AppResponse

Hierarchy

  • AppResponse

Index

interfaces-appapiappresponsemd > Properties

Properties

interfaces-appapiappresponsemd > adobeBrandType

adobeBrandType: string

Specifies the Adobe brand icon to use.


interfaces-appapiappresponsemd > appId

appId: string

Unique key to identify the app.


interfaces-appapiappresponsemd > enabled

enabled: boolean

Specifies if current user on current org is enabled to use the app.


interfaces-appapiappresponsemd > functionalIconReact

functionalIconReact: string

Specifies the app's functional icon for link locations.


interfaces-appapiappresponsemd > functionalIconUrl

functionalIconUrl: string

A URL to fetch the app's functional icon.


interfaces-appapiappresponsemd > href

href: string

Link to the app.


interfaces-appapiappresponsemd > name

name: string

Branding approved name of the app.

interfaces helpcenter.helpcenterapimd

@adobe/exc-app

Globals / helpCenter / HelpCenterApi

Interface: HelpCenterApi

Defines helpCenter-level APIs available to solutions.

Hierarchy

Index

interfaces-helpcenterhelpcenterapimd > Properties

interfaces-helpcenterhelpcenterapimd > Methods

Properties

interfaces-helpcenterhelpcenterapimd > config

config: HelpCenterConfig

Inherited from HelpCenterApiProperties.config

Gets or sets the configuration for Help Center.

helpCenter.config = {
  featured: [
    {
      href: 'https://helpx.adobe.com/support/experience-cloud.html',
      label: 'Adobe Experience Cloud Learn & Support',
      path: '/:orgId?/home'
    },
    {
      href: 'https://helpx.adobe.com/support/target.html',
      label: 'Adobe Target'
    }
  ],
  recommendations: {
    enabled: true,
    terms: [
      {
        path: '/:orgId?/analytics/home/(.*)?',
        term: 'get started'
      },
      {
        path: '/:orgId?/analytics/create',
        term: 'create new'
      }
    ]
  },
  resources: [
    {
      href: 'https://marketing.adobe.com/resources/help/en_US/home/index.html',
      label: 'Help Home'
    }
  ]
};

Methods

interfaces-helpcenterhelpcenterapimd > close

close(): void

Method to close the help center from within the iframe.

helpCenter.close();

Returns: void


interfaces-helpcenterhelpcenterapimd > open

open(config?: HelpCenterOpenConfig): void

Method to open the help center from within the iframe.

helpCenter.open({
  config: {
    subject: 'Analytics'
    type: 'CONTEXTUAL_FEEDBACK_SUBMISSION'
  },
  selectedTab: 'feedback'
});

interfaces-helpcenterhelpcenterapimd > Parameters:

Name Type
config? HelpCenterOpenConfig

Returns: void


interfaces-helpcenterhelpcenterapimd > setButton

setButton(config: HelpCenterButtonConfig | HelpCenterButtonConfig[] | null): void

Adds a custom button to the help center and enacts a callback onclick. The button will be present under the support tab in help center. The help center button may be reset by entering a null parameter.

helpCenter.setButton({
  callback: () => {},
  label: 'Create Support Ticket'
});

interfaces-helpcenterhelpcenterapimd > Parameters:

Name Type
config HelpCenterButtonConfig | HelpCenterButtonConfig[] | null

Returns: void


interfaces-helpcenterhelpcenterapimd > setButtons

setButtons(buttons: HelpCenterButtonConfig[] | null): void

Adds 1-many custom buttons to the help center and enacts a callback onclick. Depending on the scope (helpCenter or helpCenterResource), the buttons will be present under the support tab (helpCenter) or at the button of the resources section on the main tab (helpCenterResource) in help center. The help center button may be reset by entering a null parameter.

helpCenter.setButtons([{
  callback: () => {},
  id: 'support',
  label: 'Create Support Ticket',
  scope: 'helpCenter'
}]);

interfaces-helpcenterhelpcenterapimd > Parameters:

Name Type
buttons HelpCenterButtonConfig[] | null

Returns: void

interfaces helpcenter.helpcenterapipropertiesmd

@adobe/exc-app

Globals / helpCenter / HelpCenterApiProperties

Interface: HelpCenterApiProperties

Hierarchy

Index

interfaces-helpcenterhelpcenterapipropertiesmd > Properties

Properties

interfaces-helpcenterhelpcenterapipropertiesmd > config

config: HelpCenterConfig

Gets or sets the configuration for Help Center.

helpCenter.config = {
  featured: [
    {
      href: 'https://helpx.adobe.com/support/experience-cloud.html',
      label: 'Adobe Experience Cloud Learn & Support',
      path: '/:orgId?/home'
    },
    {
      href: 'https://helpx.adobe.com/support/target.html',
      label: 'Adobe Target'
    }
  ],
  recommendations: {
    enabled: true,
    terms: [
      {
        path: '/:orgId?/analytics/home/(.*)?',
        term: 'get started'
      },
      {
        path: '/:orgId?/analytics/create',
        term: 'create new'
      }
    ]
  },
  resources: [
    {
      href: 'https://marketing.adobe.com/resources/help/en_US/home/index.html',
      label: 'Help Home'
    }
  ]
};

interfaces helpcenter.helpcenterbuttonconfigmd

@adobe/exc-app

Globals / helpCenter / HelpCenterButtonConfig

Interface: HelpCenterButtonConfig

Hierarchy

  • HelpCenterButtonConfig

Index

interfaces-helpcenterhelpcenterbuttonconfigmd > Properties

Properties

interfaces-helpcenterhelpcenterbuttonconfigmd > callback

Optional callback: undefined | (value?: any) => void

Callback function to be automatically executed on click.


interfaces-helpcenterhelpcenterbuttonconfigmd > id

Optional id: undefined | string

ID of the string to use for handling callback.


interfaces-helpcenterhelpcenterbuttonconfigmd > label

label: string

Text of the button.


interfaces-helpcenterhelpcenterbuttonconfigmd > scope

Optional scope: undefined | string

Scope of the button. Options are:

  1. helpCenter: Shows as a button in the support section.
  2. helpCenterResource: Shows at the bottom of the resources section.

interfaces helpcenter.helpcenterconfigmd

@adobe/exc-app

Globals / helpCenter / HelpCenterConfig

Interface: HelpCenterConfig

Hierarchy

  • HelpCenterConfig

Index

interfaces-helpcenterhelpcenterconfigmd > Properties

Properties

interfaces-helpcenterhelpcenterconfigmd > featured

Optional featured: Array<{ href: string ; label: string ; path: string | Array<string> }>

Adds help links to the featured section of the help center.


interfaces-helpcenterhelpcenterconfigmd > questions

Optional questions: Array<string>

If the solution wants to simulate "Frequently asked questions", it can provide them as an array of strings. These appear as the user starts typing in the Search field.


interfaces-helpcenterhelpcenterconfigmd > recommendations

Optional recommendations: undefined | { enabled: boolean ; terms: Array<{ path: string ; term: string }> }

Customizes for you section of the help center.


interfaces-helpcenterhelpcenterconfigmd > resources

Optional resources: Array<{ href: string ; label: string }>

Overrides default links present in resources section. Product owners are advised to supply custom resources links to ensure greater relevance.

interfaces helpcenter.helpcenteropenconfigmd

@adobe/exc-app

Globals / helpCenter / HelpCenterOpenConfig

Interface: HelpCenterOpenConfig

Hierarchy

  • HelpCenterOpenConfig

Index

interfaces-helpcenterhelpcenteropenconfigmd > Properties

Properties

interfaces-helpcenterhelpcenteropenconfigmd > config

config: { subject: string ; type: "CONTEXTUAL_FEEDBACK_SUBMISSION" }

Configuration for Help Center fields when opened.

interfaces-helpcenterhelpcenteropenconfigmd > Type declaration:

Name Type Description
subject string String that prepopulates the subject field in the Help center feedback section.
type "CONTEXTUAL_FEEDBACK_SUBMISSION" Type of feedback. Only CONTEXTUAL_FEEDBACK_SUBMISSION is supported, meaning that the Help Center feedback tab will be opened.

interfaces-helpcenterhelpcenteropenconfigmd > selectedTab

selectedTab: "feedback"

Selected Help Center Tab. Only "feedback" is supported.

interfaces metrics.analyticsmd

@adobe/exc-app

Globals / metrics / Analytics

Interface: Analytics

The Analytics APIs are designed to mirror the Omega APIs, enabling an Analtyics record to be remotely stored which simulatenously captures additional context provided by the Metrics system at the same time that window.digitalData is sent to analytics. Two use cases are supported, described as follows.

For applications that provide Omega launch script configuration to the MetricsBrowserRuntime.init() method, the corresponding portions of the digitalData object can be supplied to the following APIs, and the Metrics SDK will store the provided object in window.digitalData, and simultaneously record the Analytics record in remote storage and call the Omega window._satellite.track() method. This approach assures consistency in the data between Omega and Metrics.

Hierarchy

  • Analytics

Index

interfaces-metricsanalyticsmd > Methods

Methods

interfaces-metricsanalyticsmd > track

track(type: "event" | "page" | "user", ...args: any): void

Complements the corresponding window._satellite.track() method and records an Analytics record.

interfaces-metricsanalyticsmd > Parameters:

Name Type Description
type "event" | "page" | "user" The type of event.
...args any Additional data to log.

Returns: void


interfaces-metricsanalyticsmd > trackEvent

trackEvent(eventData: Record<string, any>): void

Set window.digialData.eventData to the specified input and record an Analytics record.

interfaces-metricsanalyticsmd > Parameters:

Name Type
eventData Record<string, any>

Returns: void


interfaces-metricsanalyticsmd > trackPage

trackPage(pageData: Record<string, any>): void

Set window.digialData.pageData to the specified input and record an Analytics record.

interfaces-metricsanalyticsmd > Parameters:

Name Type Description
pageData Record<string, any> The object to assign to window.digitalData.pageData.

Returns: void


interfaces-metricsanalyticsmd > trackUser

trackUser(userData: Record<string, any>): void

Set window.digialData.userData to the specified input and record an Analytics record.

interfaces-metricsanalyticsmd > Parameters:

Name Type Description
userData Record<string, any> The object to assign to window.digitalData.userData.

Returns: void

interfaces metrics.historymd

@adobe/exc-app

Globals / metrics / History

Interface: History

Defines APIs used to log history events.

Hierarchy

  • History

Index

interfaces-metricshistorymd > Methods

Methods

interfaces-metricshistorymd > push

push(path: string, state?: any, ...args: any): void

Records a history push event.

interfaces-metricshistorymd > Parameters:

Name Type Description
path string The current URL.
state? any Optional. The state associated to the event.
...args any -

Returns: void


interfaces-metricshistorymd > replace

replace(path: string, state?: any, ...args: any): void

Records a history replace event.

interfaces-metricshistorymd > Parameters:

Name Type Description
path string The current URL.
state? any Optional. The state associated to the event.
...args any -

Returns: void

interfaces metrics.metricmd

@adobe/exc-app

Globals / metrics / Metric

Interface: Metric

Defines the attribute of a metric to be logged.

Hierarchy

  • Metric

Index

interfaces-metricsmetricmd > Properties

Properties

interfaces-metricsmetricmd > counter

Optional counter: undefined | number

A long integer storage column, e.g. the value when recordType = Counter.


interfaces-metricsmetricmd > data

Optional data: any

An opaque (to Metrics) object for application storage.


interfaces-metricsmetricmd > event

Optional event: string | string[]

An application-defined event.


interfaces-metricsmetricmd > level

Optional level: Level

The importance of this metric, e.g. log level.


interfaces-metricsmetricmd > message

Optional message: undefined | string

A human-readable message, e.g. console messages.


interfaces-metricsmetricmd > recordType

Optional recordType: undefined | string

The type of this metric record, may be application-specific.

interfaces metrics.metrics-1md

@adobe/exc-app

Globals / metrics / Metrics

Interface: Metrics

Defines metrics APIs.

Hierarchy

  • Metrics

Index

interfaces-metricsmetrics-1md > Properties

interfaces-metricsmetrics-1md > Methods

Properties

interfaces-metricsmetrics-1md > analytics

analytics: Readonly<Analytics>

The Analytics APIs are designed to mirror the Omega APIs, enabling an Analtyics record to be remotely stored which simulatenously captures additional context provided by the Metrics system at the same time that window.digitalData is sent to analytics. Two use cases are supported, described as follows.

For applications that provide Omega launch script configuration to the MetricsBrowserRuntime.init() method, the corresponding portions of the digitalData object can be supplied to the following APIs, and the Metrics SDK will store the provided object in window.digitalData, and simultaneously record the Analytics record in remote storage and call the Omega window._satellite.track() method. This approach assures consistency in the data between Omega and Metrics.


interfaces-metricsmetrics-1md > history

history: Readonly<History>

The History APIs are designed to mirror browser history management. Calling a Metrics history API is recommended either immediately before or after a call to window history, and will record a History record type and begin a new page load by generating a new HistoryID guid.

Methods

interfaces-metricsmetrics-1md > debug

debug(message: string, ...args: any): void

Log a debug message similar to console.debug().

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
message string The message being logged.
...args any Additional data associated to the log entry.

Returns: void


interfaces-metricsmetrics-1md > error

error(message: string, ...args: any): void

Log an error message similar to console.error().

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
message string The message being logged.
...args any Additional data associated to the error.

Returns: void


interfaces-metricsmetrics-1md > event

event(event: string | string[], ...args: any): void

Records the specified event.

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
event string | string[] The name of the event being logged.
...args any -

Returns: void


interfaces-metricsmetrics-1md > info

info(message: string, ...args: any): void

Log an informational message similar to console.info().

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
message string The message being logged.
...args any Additional data associated to the log entry.

Returns: void


interfaces-metricsmetrics-1md > log

log(message: string, args: any): void

Log an informational message similar to console.log().

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
message string The message being logged.
args any Additional data associated to the log entry.

Returns: void


interfaces-metricsmetrics-1md > start

start(name: string, ...args: any): Timer

Starts a named timer that can be used to record time taken for an operation.

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
name string The name for the timer, which is used as a prefix for the emitted timer events.
...args any Additional data associated to the timer.

Returns: Timer


interfaces-metricsmetrics-1md > store

store(metric: Metric): void

Stores the specified metric entry.

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
metric Metric The metric to be logged.

Returns: void


interfaces-metricsmetrics-1md > warn

warn(message: string, ...args: any): void

Log a warning message similar to console.warn().

interfaces-metricsmetrics-1md > Parameters:

Name Type Description
message string The message being logged.
...args any Additional data associated to the log entry.

Returns: void

interfaces metrics.metricsapimd

@adobe/exc-app

Globals / metrics / MetricsApi

Interface: MetricsApi

Defines the metrics API.

Hierarchy

  • MetricsApi

Index

interfaces-metricsmetricsapimd > Methods

Methods

interfaces-metricsmetricsapimd > create

create(name: string): Readonly<Metrics>

Creates a metrics instance for the specified component to log entries and events.

interfaces-metricsmetricsapimd > Parameters:

Name Type Description
name string The name of the component.

Returns: Readonly<Metrics>

interfaces metrics.timermd

@adobe/exc-app

Globals / metrics / Timer

Interface: Timer

Defines APIs on a timer.

Hierarchy

  • Timer

Index

interfaces-metricstimermd > Methods

Methods

interfaces-metricstimermd > time

time(event: string | { event: string }, ...args: any): number

Records the elapsed time from when the timer was created by calling Metrics.start API.

interfaces-metricstimermd > Parameters:

Name Type Description
event string | { event: string } The name of the event being logged. The {event: string} form of this argument can be used to specify the precise event name that should be recorded (the prefix supplied at construction time is ignored).
...args any -

Returns: number

The elapsed time since the timer started, in milliseconds.

interfaces network.graphqlquerymd

@adobe/exc-app

Globals / network / GraphQLQuery

Interface: GraphQLQuery

GQL Query containing graphql query and variables.

Hierarchy

  • GraphQLQuery

Index

interfaces-networkgraphqlquerymd > Properties

Properties

interfaces-networkgraphqlquerymd > query

query: string

GQL Query.

Example:

{query: `
  query userBehanceQuery($userId: String!, $apiKey: String!) {
    userBehance(userId: $userId, apiKey: $apiKey) {
      images
    }
  }`
};

{query: `
  query userBehanceQuery {
    userBehance(userId: "123@AdobeID", apiKey: "test-app") {
      images
    }
  }`
};

interfaces-networkgraphqlquerymd > variables

Optional variables: Record<string, any>

Query specific variables- key value pairs.

Example:

{variables: {
  apiKey: 'test-app',
  userId: '123@AdobeID'
 }
};

interfaces network.networkapimd

@adobe/exc-app

Globals / network / NetworkApi

Interface: NetworkApi

Hierarchy

  • NetworkApi

Index

interfaces-networknetworkapimd > Methods

Methods

interfaces-networknetworkapimd > batch

batch(input: RequestInfo, init?: BatchInit): Promise<Response>

Fetches a resource by batching it with other calls to batch made with the same priority at around the same time. For example, below two API calls would get combined into a single network call.

This is achieved by converting multiple calls to the batch API into a GraphQL query that the ExC GraphQL service has a built-in resolver for.

Supported methods: GET, POST, PATCH, DELETE.

Example:

// Batching two resource fetches into a single network call
const [batchResponse1, batchResponse2] = await Promise.all([
  batch('https://localhost/api1', {auth: 'Header', priority: 'P1'}),
  batch('https://example.com/api2', {auth: 'Header', priority: 'P1'})
]);

const request = new Request('https://localhost', {
  body: JSON.stringify({k: 'v'}),
  headers: new Headers(),
  method: 'POST'
});

// batches HTTP resources with P2(default) priority debouncing level and without Authentication token, API Key
// and returns HTTP Response {ok: true, status: 200, ...}.
batch(request);

// batches HTTP resources with P3(lowest) priority debouncing level and Authentication token, API Key in Query params
// and returns HTTP Response {ok: true, status: 200, ...}.
batch(request, {auth: 'Query', priority: 'P3'});

interfaces-networknetworkapimd > Parameters:

Name Type Description
input RequestInfo The resource that you wish to fetch. It can either be the URL of the resource you want to fetch or a Request object.
init? BatchInit An object containing any custom settings that you want to apply to the request.

Returns: Promise<Response>

The promise for the response to the batch operation.


interfaces-networknetworkapimd > fetch

fetch(input: RequestInfo, init?: FetchInit): Promise<Response>

Provides an interface for fetching resources powered by the global 'fetch' API.

Example:

// performs a window.fetch call
let response = await fetch('https://example.com/api/ping');

// performs a window.fetch call with Authorization and x-api-key headers set
response = await fetch('https://localhost', {auth: 'Header', method: 'GET'});

// performs a window.fetch call with user_token and client_id query parameters added to the URL
const request = new Request('https://localhost', {
  body: JSON.stringify({k: 'v'}),
  headers: new Headers(),
  method: 'POST'
});
response = await fetch(request, {auth: 'Query'});

interfaces-networknetworkapimd > Parameters:

Name Type Description
input RequestInfo The resource that you wish to fetch. It can either be the URL of the resource you want to fetch or a Request object.
init? FetchInit An object containing any custom settings that you want to apply to the request.

Returns: Promise<Response>

The promise for the response to the fetch operation.


interfaces-networknetworkapimd > query

query(request: QueryRequest): Promise<Response>

Provides an interface for querying resources via GraphqQL. In order to consume query, please make sure the respective query resolver is available in the GraphQL Service.

Example:

const BEHANCE_QUERY = `
  query userBehanceQuery($userId: String!, $apiKey: String!) {
    userBehance(userId: $userId, apiKey: $apiKey) {
      images
    }
  }`;

// queries the respective resource via GraphQL and returns HTTP Response {ok: true, status: 200, ...}
query({data: {query: BEHANCE_QUERY, variables: {
  userId: '123@AdobeID',
  apiKey: 'test-app',
}}, operationName: 'BehanceAvatar'});

// queries the respective resource via GraphQL and returns HTTP Response {ok: true, status: 200, ...}
query({data: {query: `
  query userBehanceQuery {
    userBehance(userId: "123@AdobeID", apiKey: "test-app") {
      images
    }
  }`
}});

interfaces-networknetworkapimd > Parameters:

Name Type Description
request QueryRequest Query request containing desired GQL Query.

Returns: Promise<Response>

The promise for the response to the query operation.

interfaces network.queryrequestmd

@adobe/exc-app

Globals / network / QueryRequest

Interface: QueryRequest

Query request interface.

Hierarchy

  • QueryRequest

Index

interfaces-networkqueryrequestmd > Properties

Properties

interfaces-networkqueryrequestmd > appId

Optional appId: undefined | string

Overwrite config.appId until federation is out. This allow scenario where sharing components that are linked to their own tenants.


interfaces-networkqueryrequestmd > data

data: GraphQLQuery | Array<GraphQLQuery>

Data containing single or multiple GQL queries.

Example:

{data: {
  query: `
    query userBehanceQuery($userId: String!, $apiKey: String!) {
      userBehance(userId: $userId, apiKey: $apiKey) {
        images
      }
    }`,
  variables: {
    userId: '123@AdobeID',
    apiKey: 'test-app'
  }
 }
};

interfaces-networkqueryrequestmd > metadata

Optional metadata: DefaultMetaData

default metadata should be given when you want to override the default metadata which will be passed with every request


interfaces-networkqueryrequestmd > operationName

Optional operationName: undefined | string

Query ID- To analyze a query's metrics & performance.

Example:

{operationName: 'BehanceAvatar'}

interfaces-networkqueryrequestmd > preferredRegion

Optional preferredRegion: ServiceDCRegions

Preferred Region should be used only for legacy apps who don't have data replication in place.

interfaces nps.nps-1md

@adobe/exc-app

Globals / nps / Nps

Interface: Nps

Defines Nps widget APIs available to solutions.

Hierarchy

Index

interfaces-npsnps-1md > Properties

interfaces-npsnps-1md > Methods

Properties

interfaces-npsnps-1md > config

config: { enabled?: undefined | false | true ; sampling?: undefined | number ; showToAdobeUsers?: undefined | false | true }

Inherited from NpsApiProperties.config

An object of nps configuration attributes for solution. By default the NPS widget is disabled. In order to enable NPS for a solution, the enabled key in the solution configuration should be set to true. NPS configuration also contains a sampling key which describes the percentage of users that will see the NPS widget. Whether NPS will be shown to Adobe users depends of the value of 'showToAdobeUsers' key. It is set to true by default.

interfaces-npsnps-1md > Type declaration:

Name Type Description
enabled? undefined | false | true Flag that enables nps for solution.
sampling? undefined | number Number that shows percent of user logins that can show nps.
showToAdobeUsers? undefined | false | true Flag that enables showing nps survey to adobe users.

Methods

interfaces-npsnps-1md > triggerNps

triggerNps(): void

Triggers calculations to evaluate whether to display NPS survey to the user and then render the NPS widget if so.

nps.triggerNps();

Returns: void

interfaces nps.npsapipropertiesmd

@adobe/exc-app

Globals / nps / NpsApiProperties

Interface: NpsApiProperties

Hierarchy

  • NpsApiProperties

    Nps

Index

interfaces-npsnpsapipropertiesmd > Properties

Properties

interfaces-npsnpsapipropertiesmd > config

config: { enabled?: undefined | false | true ; sampling?: undefined | number ; showToAdobeUsers?: undefined | false | true }

An object of nps configuration attributes for solution. By default the NPS widget is disabled. In order to enable NPS for a solution, the enabled key in the solution configuration should be set to true. NPS configuration also contains a sampling key which describes the percentage of users that will see the NPS widget. Whether NPS will be shown to Adobe users depends of the value of 'showToAdobeUsers' key. It is set to true by default.

interfaces-npsnpsapipropertiesmd > Type declaration:

Name Type Description
enabled? undefined | false | true Flag that enables nps for solution.
sampling? undefined | number Number that shows percent of user logins that can show nps.
showToAdobeUsers? undefined | false | true Flag that enables showing nps survey to adobe users.

interfaces page.blocknavigationoptionsmd

@adobe/exc-app

Globals / page / BlockNavigationOptions

Interface: BlockNavigationOptions

Hierarchy

  • BlockNavigationOptions

Index

interfaces-pageblocknavigationoptionsmd > Properties

Properties

interfaces-pageblocknavigationoptionsmd > onOrgChangeOnly

onOrgChangeOnly: boolean

Set to true if org changes are the only hash location changes that should be blocked.

Example:

{onOrgChangeOnly: true}

interfaces page.objectwithhrefmd

@adobe/exc-app

Globals / page / ObjectWithHref

Interface: ObjectWithHref

Hierarchy

  • ObjectWithHref

Index

interfaces-pageobjectwithhrefmd > Properties

Properties

interfaces-pageobjectwithhrefmd > href

href: string

The URL of the solution page.

Example:

{ href: 'https://example.com/abc' }

interfaces page.objectwithpathmd

@adobe/exc-app

Globals / page / ObjectWithPath

Interface: ObjectWithPath

Hierarchy

  • ObjectWithPath

Index

interfaces-pageobjectwithpathmd > Properties

Properties

interfaces-pageobjectwithpathmd > path

path: string

The relative path within the solution.

Example:

{path: '/abc'}

interfaces-pageobjectwithpathmd > sandbox

Optional sandbox: undefined | string

Optional sandbox name to be added to URL path.

Example:

{path: '/abc', sandbox: 'prod'}

interfaces page.pageapimd

@adobe/exc-app

Globals / page / PageApi

Interface: PageApi

Defines page-level APIs available to solutions.

Hierarchy

Index

interfaces-pagepageapimd > Properties

interfaces-pagepageapimd > Methods

Properties

interfaces-pagepageapimd > appContainer

appContainer: string

Inherited from PageApiProperties.appContainer

Configuration for specifying which element should have the left margin and top margin added to it when fullscreen overlay or modal needs to be displayed. Left margin will only be added if there is a side nav. This should be a string with an element selector.

Example:

page.appContainer = '#example'

interfaces-pagepageapimd > favicon

favicon: string

Inherited from PageApiProperties.favicon

Gets or set the favicon for the page. If this isn't set, then the default experience cloud favicon will be used.

Example:

page.favicon = "https://img.icons8.com/color/48/000000/thumb-up.png";

interfaces-pagepageapimd > modal

modal: boolean

Inherited from PageApiProperties.modal

Configuration to show/hide a modal with fullscreen overlay. Defaults to false.

Example:

page.modal = true;

interfaces-pagepageapimd > preventDefaultCombos

preventDefaultCombos: { altKey?: undefined | false | true ; ctrlKey?: undefined | false | true ; key: string ; metaKey?: undefined | false | true ; shiftKey?: undefined | false | true }[]

Inherited from PageApiProperties.preventDefaultCombos

An array of key combinations for the shell to prevent default browser behavior on in cases where an application performs some other action.

Example:

page.preventDefaultCombos = [
  {
    ctrlKey: true,
    key: 's'
  }
];

interfaces-pagepageapimd > spinner

spinner: boolean

Inherited from PageApiProperties.spinner

Gets or sets a value indicating whether or not to show a spinner on the page. This configuration value is NOT used for the initial loading spinner (see Route Configuration hideInitialSpinner for that), but can be used to dismiss it if the spinner needs to be dismissed before a solution invokes runtime.done().

Example:

page.spinner = true;

interfaces-pagepageapimd > title

title: string

Inherited from PageApiProperties.title

Gets or sets the title of the page.

Example:

page.title = 'Adobe Experience Cloud';

interfaces-pagepageapimd > unloadPromptMessage

unloadPromptMessage: string

Inherited from PageApiProperties.unloadPromptMessage

Sets a message to be displayed if the user is prompted before navigating away from the page. This will only be effective if page.blockNavigation is being used. Prompt messages should be localized based on the current locale of the user before being set. The default value is 'Are you sure?'.

Example:

page.unloadPromptMessage = 'Are you sure you want to leave?';

Methods

interfaces-pagepageapimd > blockNavigation

blockNavigation(enabled: boolean, options?: BlockNavigationOptions): void

Sometimes applications will need to block navigation away from the current page. The most common use case for this is when a user has unsaved changes that would be lost on navigation.

There are 3 types of navigation in unified shell that must be accounted for:

  1. User attempts to navigate in a way that will cause the browser to reload. This includes page refreshes, manual URL changes, and solution switcher clicks to a non-unified shell application.
  2. User attempts to navigate to another page hosted on unified shell via the shell. This includes workspace clicks, org changes, and solution switches to a unified shell application. Because this is only a hash history change, it does not cause a full browser reload.
  3. User attempts to navigate to another page in the current application via a link in the iframe.

In order to prevent the first and second types of navigation, unified shell offers a blockNavigation function. To turn on navigation blocking, the application should set:

Example:

page.blockNavigation(true);

When this function is called with true, Unified Shell will set a beforeUnload handler on the page. This will block the first type of navigation. Unified Shell will also use history.block to block hash navigations such as org switches and workspace changes. To handle the third type of navigation, applications must block the location change from within the iframe before it propogates to the shell. This is because unified shell won't know about the iframe navigation until after it happens. To solve for this, solutions should history.block from within the iframe as well. It is important to note that only push location changes should be blocked. If the solution blocks all location changes, the navigation blocking prompt will be shown to the user multiple times. When navigation blocking is no longer needed the application should set runtime.blockNavigation(false).

In special cases, a solution may want to allow workspace changes but block any other type of navigation. To enable this, the option onOrgChangeOnly should be passed in.

Example:

runtime.blockNavigation(true, {onOrgChangeOnly: true});

Please note that navigation blocking is currently only supported for tenanted solutions. If you would like to block navigation from a tenantless solution please contact a unified shell team member to discuss your use case.

interfaces-pagepageapimd > Parameters:

Name Type
enabled boolean
options? BlockNavigationOptions

Returns: void


interfaces-pagepageapimd > done

done(): void

Tells the Shell that the Solution has loaded and is ready to be used by a user and dismisses the initial loading spinner.

At the earliest, done should be called after Ready event was fired to ensure accurate reporting.

One of the main objectives of using done is to measure UX performance, it should be called after all network activity is completed and the app is interactive - Ready for users to do their work.

Example:

page.done();

Returns: void


interfaces-pagepageapimd > generateShellUrl

generateShellUrl(location: LocationLike, newApp?: undefined | false | true): string

Method to take a relative path or full iframe URL and generate a unified shell url.

Example:

// returns `https://experience.adobe.com/#/@tenant/solution/abc`
page.generateShellUrl({path: '/abc'});

// returns `https://experience.adobe.com/#/@tenant/sname:prod/solution/abc`
page.generateShellUrl({path: '/abc', sandbox: 'prod'});

// returns `https://experience.adobe.com/#/@tenant/solution/abc`
page.generateShellUrl({href: 'https://example.com/abc'});

interfaces-pagepageapimd > Parameters:

Name Type Description
location LocationLike Object with either a path and optional sandbox or href key and corresponding value from which to generate the shell URL.
newApp? undefined | false | true When true generates a new url with the given location without hash values or pathname resolutions specific to the current app.

Returns: string

The shell URL for the specified view of the solution.


interfaces-pagepageapimd > iframeReload

iframeReload(): void

Triggers the reload of the solution iframe. Calling this function will regenerate the iframe source, triggering the discovery URL flow if configured.

Example:

page.iframeReload();

Returns: void


interfaces-pagepageapimd > notFound

notFound(): void

Replaces the application iframe with the not found page.

Example:

page.notFound();

Returns: void


interfaces-pagepageapimd > openInNewTab

openInNewTab(path: string, newApp?: undefined | false | true): void

Opens the specified URL in the shell in a new tab. This is useful in scenarios where an element won't be an anchor or link and solution needs to open the URL.

Example:

page.openInNewTab('/path');

interfaces-pagepageapimd > Parameters:

Name Type Description
path string The relative path within the solution.
newApp? undefined | false | true When true generates a new url with the given location without hash values or pathname resolutions specific to the current app.

Returns: void


interfaces-pagepageapimd > shellRedirect

shellRedirect(path: string, options?: ShellRedirectOptions): void

Redirects to another unified shell solution. Path should be the complete relative path of a valid unified shell solution url (i.e. if shellRedirect is called from /target to /analytics, the path paremeter would need to start with /analytics). Query and hash are optional.

Example:

page.shellRedirect('/path?a=b#workspace');

interfaces-pagepageapimd > Parameters:

Name Type Description
path string Path including search and hash to a unified shell solution.
options? ShellRedirectOptions Options for redirect. Options include discovery which determines if the new location requires a discovery call and replace which determines if the history action should be a replace or push.

Returns: void

interfaces page.pageapipropertiesmd

@adobe/exc-app

Globals / page / PageApiProperties

Interface: PageApiProperties

Subset of page-level APIs available to solutions that are settable attributes.

Hierarchy

Index

interfaces-pagepageapipropertiesmd > Properties

Properties

interfaces-pagepageapipropertiesmd > appContainer

appContainer: string

Configuration for specifying which element should have the left margin and top margin added to it when fullscreen overlay or modal needs to be displayed. Left margin will only be added if there is a side nav. This should be a string with an element selector.

Example:

page.appContainer = '#example'

interfaces-pagepageapipropertiesmd > favicon

favicon: string

Gets or set the favicon for the page. If this isn't set, then the default experience cloud favicon will be used.

Example:

page.favicon = "https://img.icons8.com/color/48/000000/thumb-up.png";

interfaces-pagepageapipropertiesmd > modal

modal: boolean

Configuration to show/hide a modal with fullscreen overlay. Defaults to false.

Example:

page.modal = true;

interfaces-pagepageapipropertiesmd > preventDefaultCombos

preventDefaultCombos: { altKey?: undefined | false | true ; ctrlKey?: undefined | false | true ; key: string ; metaKey?: undefined | false | true ; shiftKey?: undefined | false | true }[]

An array of key combinations for the shell to prevent default browser behavior on in cases where an application performs some other action.

Example:

page.preventDefaultCombos = [
  {
    ctrlKey: true,
    key: 's'
  }
];

interfaces-pagepageapipropertiesmd > spinner

spinner: boolean

Gets or sets a value indicating whether or not to show a spinner on the page. This configuration value is NOT used for the initial loading spinner (see Route Configuration hideInitialSpinner for that), but can be used to dismiss it if the spinner needs to be dismissed before a solution invokes runtime.done().

Example:

page.spinner = true;

interfaces-pagepageapipropertiesmd > title

title: string

Gets or sets the title of the page.

Example:

page.title = 'Adobe Experience Cloud';

interfaces-pagepageapipropertiesmd > unloadPromptMessage

unloadPromptMessage: string

Sets a message to be displayed if the user is prompted before navigating away from the page. This will only be effective if page.blockNavigation is being used. Prompt messages should be localized based on the current locale of the user before being set. The default value is 'Are you sure?'.

Example:

page.unloadPromptMessage = 'Are you sure you want to leave?';

interfaces page.shellredirectoptionsmd

@adobe/exc-app

Globals / page / ShellRedirectOptions

Interface: ShellRedirectOptions

Hierarchy

  • ShellRedirectOptions

Index

interfaces-pageshellredirectoptionsmd > Properties

Properties

interfaces-pageshellredirectoptionsmd > discovery

Optional discovery: undefined | false | true

Optional boolean which specifies if the redirect requires discovery.

Example:

{discovery: true}

interfaces-pageshellredirectoptionsmd > replace

Optional replace: undefined | false | true

Optional boolean which specifies if the history action should be a replace instead of a push.

Example:

{replace: true}

interfaces pulse.pulseapimd

@adobe/exc-app

Globals / pulse / PulseApi

Interface: PulseApi

Hierarchy

  • PulseApi

Index

interfaces-pulsepulseapimd > Methods

Methods

interfaces-pulsepulseapimd > send

send(notifications: PulseNotification[]): Promise<PulseResponse>

Method to send a pulse notification.

interfaces-pulsepulseapimd > Parameters:

Name Type
notifications PulseNotification[]

Returns: Promise<PulseResponse>

interfaces pulse.pulsenotificationmd

@adobe/exc-app

Globals / pulse / PulseNotification

Interface: PulseNotification

Hierarchy

  • PulseNotification

Index

interfaces-pulsepulsenotificationmd > Properties

Properties

interfaces-pulsepulsenotificationmd > groupIds

Optional groupIds: string[]

List of group ids to receive notification.


interfaces-pulsepulsenotificationmd > messageType

messageType: NotificationType

Type of Notification to be sent.


interfaces-pulsepulsenotificationmd > metadata

Optional metadata: Record<string, string>

A map of key value pairs which can be provided by publisher of notification for the consumer.


interfaces-pulsepulsenotificationmd > sendToOrg

Optional sendToOrg: undefined | false | true

Specifies whether to send notifications to the complete IMS org.


interfaces-pulsepulsenotificationmd > templateParams

templateParams: Record<string, any>

Templated parameters.


interfaces-pulsepulsenotificationmd > userIds

Optional userIds: string[]

List of IMS user ids of the users to receive notification. A maximum of 100 user-ids are supported at a time.

interfaces pulse.pulseresponsemd

@adobe/exc-app

Globals / pulse / PulseResponse

Interface: PulseResponse

Hierarchy

  • PulseResponse

Index

interfaces-pulsepulseresponsemd > Properties

Properties

interfaces-pulsepulseresponsemd > notifications

notifications: { notification: { errorMessage: string ; notification-id: string ; statusCode: number }[] }

Notifications

interfaces-pulsepulseresponsemd > Type declaration:

Name Type Description
notification { errorMessage: string ; notification-id: string ; statusCode: number }[] Specific notification.

interfaces settings.parametersmd

@adobe/exc-app

Globals / settings / Parameters

Interface: Parameters<T>

The input parameters for the settings API.

Type parameters

Name Type
T Settings

Hierarchy

  • Parameters

Index

interfaces-settingsparametersmd > Properties

Properties

interfaces-settingsparametersmd > groupId

groupId: string

A unique identifier.


interfaces-settingsparametersmd > level

Optional level: SettingsLevel

The type of store to get/set the settings from/to. Defaults to SettingsLevel.USERORG.


interfaces-settingsparametersmd > settings

settings: T

A map of the settings key-value pairs. In case of set API, the value is saved and for the get API, the value is the fallback in case the key isn't present in the settings store.

interfaces settings.settings-1md

@adobe/exc-app

Globals / settings / Settings

Interface: Settings

A map of settings in the settings service.

Hierarchy

  • Settings

Indexable

▪ [key: string]: any

A map of settings in the settings service.

interfaces settings.settingsapimd

@adobe/exc-app

Globals / settings / SettingsApi

Interface: SettingsApi

APIs to get or set settings, preferences or configuration data that can be stored and retrieved at an IMS user and/or an IMS org level. An app in unified shell can consume Settings service.

Hierarchy

  • SettingsApi

Index

`