Skip to main content

​
Surfaces API Overview

The Surfaces API is a low-latency solution for retrieving personalized content to display in your application. This is typically an app or website, but could be any application.

When you make a request to the Surfaces API for one of your users, the API will respond with the recommended content to display to that user for each specified surface.

​
App Integration

The Surfaces API integrates into your application in one of two ways:
  • Real time
  • Pre-fetched and cached
There are some tradeoffs to consider when deciding how to integrate.

​
Real Time

  • How it works: your application calls the Surfaces API whenever a page loads with Aampe-generated content
Realtime Flow Diagram Pn
  • Advantages: simple to implement, and you only make calls only when needed
  • Disadvantages: potentially higher latency from calling out to an external service
    A common technique used when implementing this approach is to display a spinner or a skeleton screen while the data is loading.

​
Periodically Cached

  • How it works: your application calls the Surfaces API and caches the results, then pulls content from the cache whenever a page loads with Aampe-generated content
Prefetch Flow Diagram Pn
  • Advantages: no latency risk, can implement retries and other backups
  • Disadvantages: some extra work to maintain a fresh cache of content

​
Real Time vs Cached

CachedReal Time
Call TypeBackground call, on app openBlocking call, on component rendering
BatchingGet content for several surfaces at onceOne or more surfaces at a time
TimeoutLonger timeout optionsShorter timeout
RetryingTime to retry in case of network issuesNot recommended
FallbackStatic content in case of failed retries, timeouts, or API returning 404Static content in case of failed retries, timeouts, or API returning 404
ControlApp controls if, what, when to renderApp or Aampe can control if, what, when to render
TrackingApp is responsible for propagating a unique id to tracking event metadataAampe can approximate tracking without extra instrumentation

​
Surface API Latency

​
Latency SLA

The Surfaces API comes with a Service Level Agreement of P95 round trip latency of <=150ms for requests originating from within the same region as the API.

​
Reducing Latency

We recommend the following steps to reduce latency within your app when interacting with the Surfaces API
  • Pre-fetch surface content, when possible
  • Include multiple surface IDs when calling the Surface API
  • Enforce strict timeouts such that the page will load with default content in the rare cases where the API takes longer than expected to respond
  • Call the Surfaces API from within the same geographic region as the service calling the API.

​
Multi Region Deployments

To minimize latency, we recommend locating your Surfaces API deployment in the same geographic region as the service from which you will be calling the API. For instance, if your application backend runs in the us-east1 region, we can locate your Surfaces API deployment within the same region. Differences between cloud provider regions may impact our ability to directly match your region, but we will locate it as close as possible. When calling the Surfaces API, you will include the region identifier in the URL. For example, if you are using the asia-southeast1 region, you will make calls to https://content.asia-southeast1.api.aampe.com.
Work with your customer success manager to ensure your Surfaces API deployment is located in the correct region.

​
Fallback Content

In cases where the Surfaces API does not have any content to show a user for a specific Surface (e.g. if the user isn’t eligible for any of the content defined on that Surface), it’s important to define fallback content, so you still have something to show the user. Fallback content should be defined within your application. If no content is available for a given contact_id and surface_id, the API will return a 404 response.

​
Configuration Options

The Surfaces API response contains a control key which includes values you can use to govern how frequently specific Surface content is displayed in your application. 
"control": {
  "min_gap_days": 3,
  "max_displays_per_day": 1,
  "display_every_x_times": 5,
}
  • min_gap_days:minimum number of days between surface content views
  • max_displays_per_day: maximum number of personalized surface displays per day
  • display_every_x_times:a rule to show personalized surface content every X page loads (otherwise, the surface loads with fallback content).