Landing Pages for Solutions
Developers can enhance the user experience by configuring landing pages for their solutions. Landing pages direct users to specific pages within the solution based on their user group or a default setting. This guide will walk you through the process of setting up and managing landing pages for your solutions.
When a user accesses your solution, the landing page they are directed to is determined by the following rules, in order of precedence:
- If the user belongs to a single user group and that group has a landing page configured in the solution-level manifest file, the user will be directed to that landing page.
- If the user belongs to multiple user groups with configured landing pages, the user will be directed to the landing page of the user group with the highest priority (lowest rank value).
- If no user group-specific landing page matches the user's groups, if set, the default landing page configured will be used.
- If no landing pages are configured (user group-specific or solution default), the user will be directed to the first accessible app in their console sidebar.
There are two types of landing pages you can configure for your solution:
To set a default landing page for your solution:
- In the request body, include the solnUrls object with the URL of your desired default landing page.
Example:
In this example, the solnUrls object contains an object with two properties:
- name: Set to landingPage to indicate that this URL represents the default landing page for the solution.
- url: The URL of the default landing page, in this case, "https://www.example.com/default-landing-page".
If you configure a default landing page, it will direct users to this page when they access your solution, unless a user group-specific landing page is defined and takes precedence.
To configure landing pages for specific user groups:
- For each user group you want to configure a landing page for, add a landingPage attribute under the userGroupsRequired definition. This attribute should contain two properties:
- url: The relative path to the landing page for this user group
- rank: A positive integer indicating the priority of this user group in case the user belongs to more than one user group. Lower values have higher priority. For example, rank 1 is a higher priority than rank 3.
Here's an example manifest file with user group landing page configurations:
- Onboard your solution. The solution service will automatically configure the landing pages based on your manifest.
To retrieve the landing page configurations:
- For the default solution landing page: Use the GetSolution API to view the details in the solnUrls object defined when registering or updating your solution.
- For user group landing pages: Use the GetArtifacts API to retrieve the manifest file contents, including the landing page URLs and ranks for each user group.
Follow the steps below to update the default landing page for your solution and the landing pages for specific user groups.
To update the default landing page, call the UpdateSolution endpoint and include the updated solnUrls array with the new default landing page URL in the request body:
To update the landing pages for specific user groups: Edit the solution manifest YAML file and modify the landingPage attribute for the desired user groups.
2. Update the solution version using the AddSolutionVersion API:
3. Onboard the updated solution version to the tenant using the Onboarding API with the forceCreateUserGroup=true query parameter:
After updating the landing page configurations, the changes will be reflected in your solution. Users will be directed to the updated landing pages based on their user groups and the new default landing page setting.
Note: Remember to replace {solutionVersionId} in the API endpoints with the actual version ID of your solution.
If you need to remove previously configured landing pages from your solution, follow these steps:
To remove the default landing page for your solution:
- In the request body, pass null against the solnUrls object name and url parameters.
Example:
This will remove the default landing page configuration, and users will no longer be directed to the previously set default landing page when accessing your solution.
To remove landing pages for specific user groups:
- Locate the user groups for which you want to remove the landing page configuration.
- Remove the entire landingPage attribute and its sub-properties (url and rank) from each relevant user group definition.
- Onboard your solution. The solution service will automatically update the landing page configurations based on your manifest.
Example:
After removing the landing page configurations, the landing page precedence rules will be re-evaluated based on the remaining configurations. If no landing pages are configured at all (neither user group-specific nor solution default), users will be directed to the first accessible app in their console sidebar when accessing your solution.