Embed In-App Help

Use Viewport’s simplified article view to display help directly within your own app (via iFrames).

The in-app help approach allows your users to open help content directly in the right context of your app without forcing them to navigate to your Viewport help center.

Why In-App Help?

In-App Help is more than just context-sensitive help.

With context-sensitive help you place links onto specific touch points within a piece of software. These links take users directly to the corresponding piece of help content in your documentation.

If your documentation lives on the web, like it does with Viewport, the link will typically open a new tab in the browser and take the user out of their current context in your app.

With in-app help, bring your help content directly into the context of your apps without forcing users to navigate to your help center. Users still click a link in your app but the link opens an iFrame within you app where the content is readily available for reading and browsing.

How It Works

By adding a query in the URL of a help page, you can display a simplified view of your help article that's focused on the most important thing, the content. This view is ideal if you want to open help articles directly in an iFrame within your own app, as it ensures a distraction-free user experience.

If you call a help article with inAppHelp query in the URL, it will look something like this:

Page attributes that are usually part of your Viewport articles, aren't displayed when the inAppHelp query is used. These include:

• Pagetree

• Table of Contents

• Breadcrumbs

• Header

• Footer

• Third-party Integrations

Also, links within the page are opened in a new tab.

Add Help in Your App

Embed a link to your Viewport help article within your app using the inAppHelp query:

1. Implement an iframe within your app at the position where your help article should be shown. We recommend to implement the iFrame so that it opens after a user clicks on an icon or some other visual cue.

2. Get the link to the article you want to display

   • If you use Scroll Documents: We recommend to generate a link with a context key for all pages you want to display in your app. This ensures that the links you embed in the app don’t break in the future.

   • If you don’t use Scroll Documents: Just open the help article in your Viewport site and copy the URL from the browser bar.

3. Add the query ?inAppHelp=true to the link

   • With context keys, the link should look something like this: help-cloud.k15t.com/?contextKey=yourkey&version=latest?inAppHelp=true

   • With a ‘normal’ URL, the link should look something like this: help-cloud.k15t.com/scroll-viewport/get-started?inAppHelp=true

4. Use this link as the source for your iframe.

Break Up Long Articles with Page Inclusions

It may be the case that your help articles contain information related to more than one area in your app. If your user opens the in-app help, they probably want help for the specific area of the app, and not general information. You can achieve this by separating the content into separate pages in Confluence.

For example:

• In our help center we have an article with the title "Get started" which describes the onboarding process which contains 5 onboarding steps.

• In our UI the onboarding process is a step-by-step wizard. Steps 1-5.

Here is what we need to do in our help center first:

1. Create 5 new article pages, one for each onboarding step.

2. On your "Get Started" page, use Include Page macro to include the 5 articles.

Now we could already implement our in-app help feature for the 5 onboarding steps in the UI and match them with our 5 new articles.

However, in our help center navigation we would now find the original "Get Started" article with all onboarding-steps on one page in addition to the 5 new articles. To avoid this unnecessary duplication of content, we will need to add an exclude label to the 5 new articles:

scroll-help-center-exclude-page

Adding this label will exclude these articles from the navigation and search on your site. Those articles are still live and can be visited from the web, but the pages are hidden within the help center itself.

Make sure That Embedded Links Remain Stable

For software that can’t be modified after it has been deployed, it’s especially important to ensure that the links you embed always direct to helpful content. Links can easily break, for example, when you move the content you link to to a different page or replace the page where your content lives with a new page.

The best way to ensure that links don’t break is to generate your links with context keys, instead of copying the URL that is shown in the browser.

If you don’t have Scroll Documents and can’t use links with context keys, Viewport can help you recover broken links in other ways:

• Customize URLs. If you move your content to a different page, you can try to mold the URL of the new page to match the URL of the embedded link. This might not always be possible, especially if the content source or page title is not the same anymore. Read more on Customize URL Segments

• Redirects. If embedded links can’t be replicated, you can always set up redirects in Viewport. With redirects, the embedded link remains broken but redirects ensure that opening the link automatically directs users to a different page. This is especially helpful when you migrate to Viewport from other help tools. Read more on Manage Redirects .