Skip to main content

Display Custom Blocks in Purpose-built Apps

Summary​

Task: Configure Custom Block tabs to add custom functionality to your Purpose-built App

Time estimate: 20-30 minutes

Skill level: Intermediate

Prerequisites​

  • Purpose-built App project initialized
  • Custom Block plugin created and published
  • Basic understanding of JSON configuration
  • Custom Block plugin ID available

Steps​

Step 1: Create or Identify Your Custom Block​

Before adding a Custom Block to your Purpose-built App, you need a published Custom Block plugin.

If you need to create a Custom Block:

Follow the Custom Block Quickstart to create your plugin. The Purpose-built App Quickstart also includes step-by-step guidance for creating and integrating Custom Blocks.

Key information needed:

  • Plugin ID (format: PLUG_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  • Your Custom Block should be published and accessible to your users

Step 2: Add Custom Block Tab Configuration​

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

{
  "metadata": {
    "tabs": [
      {
        "type": "purposeBuiltAppTabPlugin",
        "pluginId": "PLUG_1b649f3f-160a-444c-b2cc-f21209cb2898",
        "iconName": "HelpIcon",
        "themeType": "blue",
        "order": 2
      }
    ]
  }
}

Key fields explained:

FieldPurposeExample
typeMust be "purposeBuiltAppTabPlugin""purposeBuiltAppTabPlugin"
pluginIdID of your Custom Block plugin"PLUG_1b649f3f..."
iconNameIcon to display on the tab"HelpIcon"
themeTypeColor theme for the tab"blue"
orderDisplay position (1 = first tab)2

Step 3: Configure Tab Appearance​

Customize how your Custom Block tab appears in the navigation:

Available icon names:

  • HelpIcon
  • SettingsIcon
  • DashboardIcon
  • ReportsIcon
  • TicketsIcon
  • And many more (see Tab icons)

Available theme types:

  • blue
  • green
  • greenblue
  • purple
  • yellow
{
  "iconName": "DashboardIcon",
  "themeType": "green",
  "order": 1
}

Step 4: Add Navigation Between Tabs (Optional)​

If your Custom Block needs to navigate to other tabs in your Purpose-built App, use the changePbaTab function from the Custom Block SDK.

In your Custom Block's React component:

// `client` is automatically passed into your component via props
function navigateToTab() {
  client.changePbaTab('some-other-tab');
}

// In your component
<button onClick={() => client.changePbaTab('tickets')}>
  Go to Tickets
</button>

Navigation patterns:

Target Tab TypeArgument FormatExample
Content tabUse the tab's id propertyclient.changePbaTab('home')
Custom Block tabUse the plugin's pluginIdclient.changePbaTab('PLUG_...')

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 Custom Block tab
  4. Verify your Custom Block loads correctly
  5. Test any navigation functions between tabs

Checkpoint: You should see your Custom Block displayed within the Purpose-built App tab, and all navigation should work smoothly.

Common Issues and Solutions​

Issue: Custom Block Not Loading​

Symptoms: Tab appears but shows a blank page or error

Causes:

  • Incorrect pluginId
  • Custom Block not published
  • User lacks permissions to access the plugin

Solution:

  1. Verify the pluginId matches your published Custom Block
  2. Check that the Custom Block is published (not in draft state)
  3. Confirm your user account has access to the plugin
  4. Check browser console for specific error messages

Issue: Navigation Not Working​

Symptoms: changePbaTab calls don't navigate to other tabs

Causes:

  • Target tab ID doesn't match configuration
  • Using wrong ID format for tab type

Solution:

For content tabs, use the id from config:

// In config.json
{"id": "tickets", "type": "content", ...}

// In Custom Block
client.changePbaTab('tickets'); // ✅ Correct

For Custom Block tabs, use the pluginId:

// In config.json
{"pluginId": "PLUG_abc123", "type": "purposeBuiltAppTabPlugin", ...}

// In Custom Block  
client.changePbaTab('PLUG_abc123'); // ✅ Correct

Issue: Multiple Custom Blocks Conflict​

Symptoms: Wrong Custom Block loads when clicking tabs

Causes:

  • Duplicate pluginId values
  • Plugin caching issues

Solution:

  • Ensure each Custom Block tab has a unique pluginId
  • Clear browser cache and reload
  • Verify each plugin ID matches the intended Custom Block

Alternative Approaches​

Embedding Multiple Custom Blocks​

To display multiple custom features, create separate tab entries:

"tabs": [
  {
    "type": "purposeBuiltAppTabPlugin",
    "pluginId": "PLUG_dashboard-plugin",
    "iconName": "DashboardIcon",
    "themeType": "blue",
    "order": 1
  },
  {
    "type": "purposeBuiltAppTabPlugin",
    "pluginId": "PLUG_reports-plugin",
    "iconName": "ReportsIcon",
    "themeType": "green",
    "order": 2
  }
]

Mixing Custom Blocks with Content Tabs​

Create a unified experience by combining native Qualtrics pages with custom functionality:

"tabs": [
  {
    "type": "content",
    "id": "tickets",
    "href": "/tickets/app",
    "order": 1
  },
  {
    "type": "purposeBuiltAppTabPlugin",
    "pluginId": "PLUG_custom-dashboard",
    "order": 2
  }
]

Best Practices​

Performance​

  • Lazy load Custom Blocks to reduce initial app load time
  • Minimize Custom Block bundle sizes
  • Cache data appropriately within your Custom Block
  • Use the Custom Block SDK efficiently

Security​

  • Validate all user inputs within Custom Blocks
  • Follow Custom Block security best practices
  • Use appropriate authentication for API calls
  • Don't expose sensitive data in client-side code

Maintenance​

  • Version your Custom Block plugins
  • Document the purpose of each Custom Block tab
  • Keep Custom Block dependencies updated
  • Test Custom Blocks after Purpose-built App updates

Recap​

You've successfully configured a Custom Block tab in your Purpose-built App. Your tab now:

  • Displays your custom functionality
  • Integrates seamlessly with your app's design
  • Supports navigation between tabs
  • Provides a unified user experience

Related Content​