Help Center Guidelines

This page provides guidelines for integrating Zendesk Help Center articles with the iOS SDK. It covers required URL patterns, host mapping and branding, and best practices to ensure articles load reliably for your users.

For instructions on how to set up and manage Guide articles in Zendesk, see: Help Center documentation

Help Center article URL guidelines

To ensure that articles load correctly in the SDK and avoid 404 errors, all Help Center article URLs must match the following regex pattern:

/hc/([a-z-]+)/articles/(\d+)(?:[/-]?.*)?$

• ([a-z-]+): The language/locale code for the article (e.g., en-us, fr, de).
• (\d+): The numeric ID of the article (e.g., 123456789).
• The pattern allows for optional trailing slashes, dashes, or other characters after the article ID.

Examples:

• /hc/en-us/articles/123456789
• /hc/fr/articles/987654321/
• /hc/de/articles/123456789-some-article-title

Important:

• If your article URLs do not match this pattern, the SDK will not be able to load them and users may see 404 errors.
• If you need to override the SDK's default link handling (for example, to open articles in a browser), see the Click Delegates documentation.

Following these guidelines will ensure a consistent and reliable experience for users accessing Help Center articles through the SDK.

Host mapping and branding

The Article Viewer in the SDK is designed to inherit the branding settings of your Zendesk account, ensuring a seamless and consistent user experience for your end users.

How host mapping works

• Branding Settings: During SDK initialization, branding settings are retrieved using your channel_id. These settings include the account's host mapping URL, which is used to verify the origin of articles.
• URL Validation:
  • The SDK checks if a provided URL is valid for your account. If a brand exists, it validates the host mapping against the URL.
  • The SDK further validates whether the URL matches a valid guide article URL pattern.
• Fallback: If no host mapping is defined for the account, the SDK will fall back to using the subdomain of your Zendesk account for validation.

Why this matters: By aligning the Article Viewer with your account's branding and host mapping, the SDK ensures that users always see articles with the correct look and feel, and that only valid, trusted article URLs are loaded.

Note: If you have not set up host mapping for your account, articles will be served from your Zendesk subdomain by default.

For instructions on setting up host mapping, see Setting up host mapping in Guide.

Restricted Articles

If the article requires authentication and a 401 error is encountered, this triggers the Article Viewer to be dismissed and the article link to be opened in an external browser outside of the application.

Due to the differences between the Classic SDK and the Messaging SDK authentication systems, we cannot authenticate Guide users. As a result, the SDK is unable to access APIs that require user authentication.

FAQ

Q: Why am I seeing 404 errors when loading Help Center articles in the SDK?
A: Ensure your article URLs match the required pattern: /hc/de/articles/123456789-some-article-title. If the pattern is not followed, the SDK cannot load the article.

Q: How do I set up and manage Guide articles?
A: See the Help Center documentation for instructions on creating and managing articles.

Q: What if my account does not have host mapping configured?
A: The SDK will fall back to using your Zendesk subdomain for article URLs if host mapping is not set up.

Q: Can I override how article links are handled in the SDK?
A: Yes, you can use the Click Delegates feature to override the default link handling. See the Click Delegates documentation for details.

Q: How does the SDK ensure articles match my account's branding?
A: The SDK retrieves branding settings during initialization and uses them to validate and display articles with the correct look and feel.

Q: What happens if a user tries to access a restricted (authenticated) article?
A: If the article requires authentication and a 401 error occurs, the Article Viewer will close and the article link will open in an external browser outside the application.