Skip to main content

Display Qualtrics Pages in Purpose-built Apps

Summary​

Task: Configure content tabs to display native Qualtrics pages within your Purpose-built App

Time estimate: 15-20 minutes

Skill level: Intermediate

Prerequisites​

  • Purpose-built App project initialized
  • Basic understanding of JSON configuration
  • Familiarity with Qualtrics page URLs

Steps​

Step 1: Identify the Qualtrics Page​

Determine which Qualtrics page you want to display in your Purpose-built App. Common pages include:

  • Tickets: /tickets/app
  • Dashboards: /dashboard/*
  • Reports: /reports/*
  • Surveys: /survey-builder/*

You can find the URL by navigating to the desired page in Qualtrics and examining the URL path.

Step 2: Add a Content Tab Configuration​

Open your config.json file and add a new tab object to the tabs array within the metadata section:

{
  "metadata": {
    "tabs": [
      {
        "nameKey": "tabName",
        "type": "content",
        "id": "home",
        "iconName": "TicketsIcon",
        "href": "/tickets/app",
        "themeType": "green",
        "activeForGlobalWrapperConfigTypes": [
          {
            "contextType": "Tickets"
          }
        ],
        "URLAllowList": ["/tickets/app*"],
        "requirements": {
          "AccountPermissions": []
        },
        "order": 1
      }
    ]
  }
}

Key fields explained:

FieldPurposeExample
typeMust be "content" for Qualtrics pages"content"
idUnique identifier for the tab (appears in URL)"home"
hrefPath to the Qualtrics page to display"/tickets/app"
URLAllowListURL patterns allowed within this tab["/tickets/app*"]
iconNameIcon to display on the tab"TicketsIcon"
themeTypeColor theme for the tab"green"
orderDisplay position (1 = first tab)1

Step 3: Configure the URL Allow List​

The URLAllowList field is critical for proper navigation. It defines which URLs can be displayed within the tab:

"URLAllowList": ["/tickets/app*"]

Best practices:

  • Use wildcard patterns (*) to allow sub-pages
  • Be specific to prevent overlap between tabs
  • Include all navigation paths users might access within that feature

Example for a dashboard tab:

"URLAllowList": [
  "/dashboard/*",
  "/reports/dashboard/*"
]

Step 4: Set Active Context (Optional)​

The activeForGlobalWrapperConfigTypes field controls when the tab appears active in the global navigation:

"activeForGlobalWrapperConfigTypes": [
  {
    "contextType": "Tickets"
  }
]

This ensures the tab highlights correctly when users navigate within that Qualtrics feature area.

Step 5: Test the Configuration​

  1. Save your config.json file
  2. Rebuild and deploy your Purpose-built App
  3. Navigate to your app and click the new tab
  4. Verify the Qualtrics page loads correctly
  5. Test navigation within the page to ensure URLs stay within the tab

Checkpoint: You should see the Qualtrics page displayed within your Purpose-built App tab, and navigation should work smoothly without breaking out of the app.

Common Issues and Solutions​

Issue: Tab Shows Blank Page​

Symptoms: Tab loads but displays a blank white page

Causes:

  • Incorrect href path
  • Missing permissions for the page
  • URL not in allow list

Solution:

  1. Verify the href matches the actual Qualtrics page URL
  2. Check that your user account has access to that feature
  3. Ensure href is included in URLAllowList

Issue: Navigation Breaks Out of App​

Symptoms: Clicking links within the page navigates away from the Purpose-built App

Causes:

  • URLAllowList too restrictive
  • Missing wildcard patterns

Solution: Expand your URLAllowList to include navigation paths:

"URLAllowList": [
  "/tickets/app*",
  "/tickets/ticket/*"
]

Issue: Multiple Tabs Show the Same Content​

Symptoms: Different tabs display identical content

Causes:

  • Overlapping href or URLAllowList patterns
  • Duplicate id values

Solution:

  • Ensure each tab has a unique id
  • Review URLAllowList patterns to eliminate overlap
  • Use more specific paths

Alternative Approaches​

Using Dynamic Routing​

For pages with variable IDs, use pattern matching:

"href": "/dashboard/{dashboardId}",
"URLAllowList": ["/dashboard/*"]

Multiple Pages in One Tab​

To display related pages in a single tab, use broader patterns:

"URLAllowList": [
  "/feature/*",
  "/related-feature/*"
]

Best Practices​

Performance​

  • Minimize the number of tabs to reduce overhead
  • Use specific URL patterns rather than overly broad wildcards
  • Consider lazy loading for rarely accessed features

Security​

  • Only expose features your users need access to
  • Use requirements field to enforce permissions
  • Regularly audit exposed URLs

Maintenance​

  • Document which Qualtrics pages each tab displays
  • Keep URL patterns updated as Qualtrics evolves
  • Test after Qualtrics platform updates

Recap​

You've successfully configured a content tab that displays a Qualtrics page within your Purpose-built App. Your tab now:

  • Displays the specified Qualtrics feature
  • Maintains proper navigation within the tab
  • Integrates seamlessly with your app's design
  • Enforces appropriate access controls

Related Content​