Customer cards

Customer cards are a powerful feature in Plain which let you configure what gets shown in the customer panel. The key features of cards are that they are:

• pulled from your backend APIs instead of pushed. This means you don't have to write code that syncs your customer data to Plain.
• cached for any timeframe between 15 seconds and 1 year. This allows you to control how often Plain should reload a card. Caching cards in Plain will also improve performance for your Support App users.
• defined using a JSON schema, so you don't have to worry about CSS and visuals and only need to focus on the data and how you want it laid out.
• will automatically reload if a user is viewing a customer, and it expires, therefore guaranteeing that the data they see is always the latest.
• can be reloaded manually if a user wants a fresh copy of the card.

Terminology

• Customer Card Config: the configuration of each card in the customer's panel. It defines the title of the card, where it should be loaded and a default time to live value.
• Customer Card Instance: a specific instance of a loaded card. In most cases the documentation refers to these as "customer cards", but the API schema uses the precise term. The instances are cached until they expire.

Architecture

At a high level three main components are working together to deliver customer cards:

1. The Support App when it loads a customer queries the Plain backend for any cards.
2. The Plain backend then:
   1. Returns cached cards that are still within their TTL (time to live) value
   2. Requests any cards that are missing or past their TTL, using their card key
3. Your API(s) will then receive a request from Plain for specific card keys
   • In the request body you'll get the customer's email, externalId, and the requested card keys.
   • You can build multiple APIs to return any number of cards

API calls to your endpoint are optimized so that cards that share the same API URL and API headers will be made in one request instead of multiple.

Plain will send a request like the example below to your API based on your customer card config:

{
  "cardKeys": [
    "plan-details",
    "subscription-status"
  ],
  "customer": {
    "email": "alex@grocery.co",
    "externalId": "your_user_id_795BFCD5-130F-4E72-BD46-14F717BE0830"
  }
}

Your API should then reply with a response of cards, where each requested card key is returned with the components to display:

{
  "cards": [
    {
      "key": "plan-details",
      "timeToLiveSeconds": 86400,
      "components": [
        {
          "componentRow": {
            "rowMainContent": [
              {
                "componentText": {
                  "text": "Plan",
                  "textColor": "MUTED",
                  "textSize": "M"
                }
              }
            ],
            "rowAsideContent": [
              {
                "componentBadge": {
                  "badgeLabel": "Starter",
                  "badgeColor": "YELLOW"
                }
              }
            ]
          }
        }
      ]
    },
    {
      "key": "subscription-status",
      "timeToLiveSeconds": 60,
      "components": null
    }
  ]
}

Plain UI components

You can use the Plain UI components to define how your customer data should be laid out and presented to the user. All the components are documented in the Plain UI Components section. For example customer cards and an example API you can check out team-plain/example-customer-cards.

You can use the https://example-customer-cards.plain.com/ static JSON API in your configuration to try out this feature or open it up in your browser to see what a few example cards look like.

HTTPie and curl commands

http POST https://example-customer-cards.plain.com/

curl -X POST https://example-customer-cards.plain.com/ | jq .

Caching of cards

Caching of customer cards is controlled via two properties:

1. A default time to live value (in seconds) on the customer card config. This can be changed under Settings -> Customer Cards. Any changes will only apply to newly loaded customer cards.
2. An explicit time to live value (in seconds) in the Customer Card API response with the key timeToLiveSeconds. This allows your API to dynamically set the TTL using custom logic.

Any card that is past its expiry time will usually be deleted within a few minutes, but latest within 48 hours of it expiring.

Playground

The Customer Cards Playground lets you build and preview the component JSON needed to create a customer card. Use this to prototype a customer card before starting to build your integration.

Customer Cards vs. Custom Timeline Entries

Customer Cards are used to add context to a customer's panel which is always visible. This is useful if the key information shown in customer cards is always relevant. If you want to show events that happened at a specific point in time, then using Custom Timeline Entries is more appropriate.

Pricing

Loading and caching of Customer Cards for a customer will not count towards your usage of monthly active customers. We think having the full context for a customer should be a given, rather than premium.

Building your Customer Cards API

To build your own API endpoint head over to Building a Customer Card API for more detailed technical documentation.