Personalised Docs

You can customize the docs for your readers, making it easier for them to find the information they need without switching between different sources.

Here are some things in your docs that can be personalized:

• User ID,
• User Name,
• API Keys,
• API version they're currently using,
• Plan they are on,
• Their permissions...

How to Personalize Docs

You can use variables to personalize the docs for your readers. For example, if you accessed this documentation through Help & Support, you would see your name on the first page and here as well.

Variables can be injected into the docs in two ways:

• By sending your readers to a docs URL having certain query parameters.
• By writing a cookie.
• By using a custom login flow.

When the variables are injected, the documentation will dynamically display the information that is most relevant to the reader.

Personalizing through URL

Variables can be injected into a page through the URL. You can provide the variables in two ways:

• Clear text: Add it in a URL query vars. For example ?vars={"user":{"name": "John"}}
• Base64: Add it in a URL query hvars. For example ?hvars=eyJ1c2VyIjp7Im5hbWUiOiJKb2huIn19

As an example, if you load this documentation from this link:

https://docs.developerhub.io/?vars={"user":{"name": "John"}}

You will be welcomed as a person named John.

Personalizing through Cookie

You can customize your site by setting a cookie that your docs site can read. Using a cookie for personalization is better than using URL personalization because the variables won't be visible in the URL box.

The cookie should be set on the main site, not just on the docs site. For example, if your main site is pied-piper.com and your docs are at pied-piper.com/docs, set the cookie on pied-piper.com so it can be accessed from pied-piper.com/docs.

Cookies can only be read on the same root domain, even if you're using subdomains. For example, you can set a cookie on: pied-piper.com and make it accessible on docs.pied-piper.com and pied-piper.com/docs. However, if your documentation site is on a different root domain like pied-docs.com, you need to personalize using URL or custom login.

To inject variables with a cookie, include the following in the cookie:

Name: vars

Value: eyJ1c2VyIjp7Im5hbWUiOiJKb2huIn19 # Base64 of the variables JSON

Domain: .docs.pied-piper.com # Custom domain of your docs

Path: / # Basepath of your docs, if you have multiple projects on same custom domain

Expires: Thu, 18 Dec 2022 12:00:00 UTC # As needed

HttpOnly: false

Secure: true

SameSite: Lax

For example, to create a cookie using JavaScript:

let vars = {"user": {"name": "John"}};

​

document.cookie = "vars=" + btoa(JSON.stringify(vars)) + "; expires=Thu, 18 Dec 2022 12:00:00 UTC; path=/; domain=docs.pied-piper.com; SameSite=lax; Secure";

Standard for User Details

To customize your documents, use this standard for all current and future features. Please follow this JSON format:

{

  "user": {

    "id": 8

    "email": "email@address.com",

    "name": "User Name"

  }

}