Routing
The routing mechanism enables apps to easily navigate to any page within the SHOPLINE Admin, and also supports opening specified pages in new browser tabs by calling relevant APIs. For example, if your app is a payment app and a merchant enters your app after completing the authorization and installation, you can use the specific routing API to seamlessly navigate to the payment app's activation page.
The following sections describe the relevant API methods.
replaceTo
Replaces the current browser address and navigates to a specified external URL.
Method signature
replaceTo(url: string): void
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| url | string | The full URL to navigate to. | Yes |
Example
import { Redirect } from '@shoplineos/app-bridge';
const redirect = Redirect.create(app);
// Navigate to the SHOPLINE official website.
redirect.replaceTo('https://www.shopline.com');
// Navigate to an external page.
redirect.replaceTo('https://****app.com/dashboard');
routerTo
Performs a routing navigation within the SHOPLINE Admin, used to navigate to different pages of the store (such as the Orders page and Products page). The navigation stays within the same browser tab.
Method signature
routerTo(path: string): void
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| path | string | The routing path within the SHOPLINE Admin, starting with /. | Yes |
Common routing paths
| Path | Description |
|---|---|
/orders | Order list page |
/products | Product list page |
/customers | Customer list page |
/apps/${appKey} | Specific app page |
Example
import { Redirect } from '@shoplineos/app-bridge';
const redirect = Redirect.create(app);
// Navigate to the order list page.
redirect.routerTo('/orders');
// Navigate to the product list page.
redirect.routerTo('/products');
// Navigate to an app page.
const yourAppHandle = 'your-app-handle';
redirect.routerTo(`/apps/${yourAppHandle}`);
toAdminPage
Navigates to a specific business page within the SHOPLINE Admin (such as a details page and creation page). This method supports richer parameter configuration, such as the setting of whether to open in a new browser tab, suitable for scenarios requiring precise control over navigation behaviors.
Method signature
toAdminPage(
section: ADMIN_SECTION,
options?: RedirectParam | RedirectOauthParam | RedirectPurchaseParam
): void
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| section | ADMIN_SECTION | The type of business page to navigate to. | Yes |
| options | RedirectParam | RedirectOauthParam | RedirectPurchaseParam | Navigation parameter configuration (varies depending on the business type). | No |
ADMIN_SECTION enumeration values
| Value | Description | Applicable options type | Remarks |
|---|---|---|---|
SALES | Discount list page | RedirectParam | - |
ORDERS | Order list page | RedirectParam | - |
PRODUCTS | Product list page | RedirectParam | - |
CUSTOMER | Customer list page | RedirectParam | - |
CATEGORIES | Category list page | RedirectParam | - |
OAUTH | Authorization page | RedirectOauthParam | Used for app authorization. |
PACKAGE_PURCHASE | Plan purchase page | RedirectPurchaseParam | appKey is required. |
RedirectParam type
Used for navigating to a list page, details page, or creation page.
| Parameter | Type | Description | Required |
|---|---|---|---|
| id | string | Resource ID. If provided, navigates to the corresponding details page. For example, passing a product ID will navigate to the product details page in the SHOPLINE Admin. | No |
| newContext | boolean | Whether to open in a new browser tab. • true: Opens in a new tab• false: Navigates within the current tab | No |
| create | boolean | Whether to navigate to a creation page. • true: Navigates to a creation page• false: Navigates to a details page (if id is provided) or a list page | No |
RedirectOauthParam type
Used for navigating to the authorization page.
| Parameter | Type | Description | Required |
|---|---|---|---|
| oauthInfo | OauthConfig | Authorization configuration information. | Yes |
Regarding the OauthConfig type, refer to the following table:
| Parameter | Type | Description | Required | Required |
|---|---|---|---|---|
| scope | string | Permission scope. Use , to separate multiple permissions, for example, read_products,read_orders. For the complete permission list, refer to Access scope. | Yes | Yes |
| appKey | string | The unique identifier of the app. | Yes | Yes |
| redirectUri | string | The callback URL to redirect to after authorization is completed. It must be the same as one of the app callback URLs configured in the Partner Portal. | Yes | Yes |
RedirectPurchaseParam type
Used for navigating to the plan purchase page.
| Parameter | Type | Description | Required |
|---|---|---|---|
| appKey | string | The unique identifier of the app. | Yes |
Example
import {
Redirect,
ADMIN_SECTION,
type RedirectParam,
type RedirectOauthParam,
type RedirectPurchaseParam,
type OauthConfig,
} from '@shoplineos/app-bridge';
const redirect = Redirect.create(app);
// Example 1: Navigate to a category details page
const categoryParams: RedirectParam = {
id: '1000001', // Category ID
newContext: true, // Opens in a new tab
};
redirect.toAdminPage(ADMIN_SECTION.CATEGORIES, categoryParams);
// Example 2: Navigate to a product creation page
const createProductParams: RedirectParam = {
create: true, // Navigate to the creation page
};
redirect.toAdminPage(ADMIN_SECTION.PRODUCTS, createProductParams);
// Example 3: Navigate to the authorization page
const oauthParams: RedirectOauthParam = {
oauthInfo: {
appKey: 'your-app-key',
scope: 'read_products,write_products',
redirectUri: 'https://your-app.com/callback',
},
};
redirect.toAdminPage(ADMIN_SECTION.OAUTH, oauthParams);
// Example 4: Navigate to the plan purchase page
const purchaseParams: RedirectPurchaseParam = {
appKey: 'your-app-key',
};
redirect.toAdminPage(ADMIN_SECTION.PACKAGE_PURCHASE, purchaseParams);