This article helps you integrate personalized and unique functionality into your Zendesk help center. It guides you through the process to add custom pages to your Knowledge Enterprise plan and explains how you can develop, bundle, and embed custom pages using technologies such as React.js and Node.js.
For instance, you can create a custom VIP Support sign-up page that fits seamlessly with your existing help center design, providing a cohesive and tailored user experience.
This single-page app example uses React with TypeScript for the frontend and Node.js for the backend. Tailwind CSS styles the app, and Nodemailer manages email confirmations for new users who successfully sign up.
Since you work with a React app, the example covers the Webpack steps to compile it into a single file. You embed the file in your help center theme and upload it. Follow the sections below for each set of steps:
- Step 1: Develop the custom page using React with TypeScript and Node.js
- Step 2: Configure Webpack to bundle the custom page
- Step 3: Embed and integrate the project into your theme and publish it to the help center
If you don't want to integrate with a backend or use TypeScript, check out the boilerplate to start your own single-page app.
Step 1: Develop the custom page using React with TypeScript and Node.js
Custom pages let you develop using any preferred web tech stack. Many developers prefer React.js with Node.js for backend development. Each technology has its own nuances and specifications. Consider the following technical points:
React
Use Create React App for custom pages since this framework supports single-page applications. The VIP Support sign-up page above makes two requests: one request generates a secure token for backend authentication, and the other submits actual data.
The example custom page changes user profiles and organizations within Zendesk. If your page makes similar requests, validate data from the frontend before you send the request. Backend validation plays a crucial role, but frontend validation ensures clean data, especially from user inputs.
Remember that a custom page forms just one part of your help center. Ensure any functionality, branding, or styling aligns with your help center as a whole.
Consider these design aspects:
- Authentication: Specify who can access this page: agents, all authenticated users, or every user.
- Navigation:
- Avoid developing a header or navigation on your custom page. The Knowledge team of your account sets these features. The custom page inherits the current theme's header and navigation.
Position this page appropriately within the help center. Like the functionality, the custom page exists outside the default help center schema. Users reach these pages via links in any help center template or predefined pages like your home page. Custom page URLs look like this:
https://{domain_name}/hc[/{locale}]/p/{page_name}
- Page styling: Select styling libraries that fit the help center theme. Make sure your font and color palette match your existing theme.
- Image handling: Since you manually configure and bundle your custom page, storing images or assets locally does not work. Upload them to your help center theme before embedding. For step-by-step instructions, refer to the article: Using your own theme assets for help center.
Node.js
Custom pages give you a blank canvas to build a personalized experience for your visitors. With tools like Node.js and Express, you can connect directly to existing systems and databases. You can also create new services with your preferred tech stack and integrate them with your help center for a seamless user experience.
The example app uses the functions below.
- The developers created an Express API that receives the user and organization information submitted by the frontend form.
- The app sends API requests to Zendesk Support to create and update the relevant user and organization using node-fetch.
- It validates the form submission data using validator.js.
- The app sends a confirmation email notification to the user on successful form submission using Nodemailer.
Protect your API routes carefully when you build server-side custom page services. Use tools such as JWT to secure your application by building request authentication. For more details on JWT, see this article from the JWT website: JSON Web Token Introduction.
The example app uses the authentication described below.
- The developers created an authentication endpoint that the frontend uses to request a JWT token and authorize requests to the form submission API.
- The authentication modules generate and verify JWT tokens using jsonwebtoken.
Depending on the application you build, consider your CORS (Cross-Origin Resource Sharing) policy. Ensure that the routes that receive requests from the client side have CORS enabled. If you know the domains that send the requests, specify these domains explicitly. Otherwise, configure the wildcard *. For more information on CORS, see this article from Mozilla's website: Cross-Origin Resource Sharing (CORS).
Step 3: Configure Webpack to bundle the custom page
Once you complete the development of your custom page, bundle your React app using Webpack. Because your theme needs to embed all custom pages, compile the custom page into a single HTML file. The Create React App includes its own bundling and optimization. However, since you aim to return a single index.html file, the example uses its own webpack configuration to simplify this process.
Step 4: Embed and integrate the project into your theme and publish it to the help center
After you build your application, embed it into your help center. Navigate to the newly created build directory. You will find a few files needed to create the new custom page.
index.htmlstatic/css/bundle.min.cssstatic/bundle.min.js
The index.html file contains the code you put into the custom page. Access the JavaScript and CSS created for the project. First, upload the JavaScript and CSS files as assets into your help center. Then, copy the code from your index.html file into the custom page and adjust the file paths to point to the assets.
See an example below of how this appears in the code editor.
After you finish, publish your custom page. For additional resources about managing content in your help center, see the article: Knowledge resources.