Skip to main content

Get Context API

Get Context API provides a functionality for retrieving a context object from a backend API endpoint using an HTTP GET request. The response is a JSON object containing multiple namespaces, each with its own set of context keys and values. These keys are stored as Context Keys.

This API could be used to pull location information, specific app parameters (for example determine which environment to use staging or production), etc.

This API will be consumed by the Context Setter Plugin.

Request​

The Get Context API accepts an HTTP GET request to the endpoint /get-context (for example).

Example request:

GET /get-context HTTP/1.1
Host: example.com

Runtime URL Configuration​

The Context Setter Plugin can be configured with a runtime URL that determines where to fetch context data from. The URL itself remains fixed, but you can configure additional parameters through Endpoints.

Endpoints allow you to add context keys as query parameters, headers, or authentication tokens to URLs based on string matching. When the Context Setter Plugin makes an HTTP GET request to the configured runtime URL, any matching endpoint configuration will automatically append the specified context keys to the request. This enables flexible context fetching based on different environments (development, staging, production) or user-specific parameters like access tokens.

Response​

If the backend API endpoint responds with an HTTP status code of 200, the Get Context API will return an HTTP status code of 200 along with the response body, which will be a JSON object with multiple namespaces and their corresponding context keys and values.

Example response body:

{
  "version": 1,
  "storage_keys": {
    "namespace1": {
      "contextKey1": "VALUE",
      "contextKey2": "VALUE"
    },
    "namespace2": {
      "contextKey1": "VALUE",
      "contextKey2": "VALUE"
    }
  },
  "persistent_keys": {
    "namespace1": {
      "persistentKey1": "VALUE",
      "persistentKey2": "VALUE"
    }
  }
}

These values will be stored as Context Keys.

Storage Keys vs Persistent Keys​

The response supports two types of key storage:

  • storage_keys: Context keys that are stored in memory only and will be cleared when the app is restarted or when new context data is fetched. These are temporary context values.

  • persistent_keys: Context keys that are persisted to local storage and will survive app restarts. These keys remain available across sessions until explicitly cleared or overwritten by a new API call.

Both storage_keys and persistent_keys follow the same namespace structure, where each namespace can contain multiple key-value pairs. The keys are then accessible as Context Keys throughout the application.

Usage Examples​

Example 1: Session-Only Data​

Use storage_keys for temporary session data that should be cleared on app restart:

{
  "version": 1,
  "storage_keys": {
    "session": {
      "sessionId": "abc123xyz",
      "temporaryToken": "temp_token_12345"
    }
  }
}

Example 2: Persistent User Preferences​

Use persistent_keys for data that should persist across app sessions:

{
  "version": 1,
  "persistent_keys": {
    "userPreferences": {
      "selectedRegion": "US",
      "contentLanguage": "en"
    }
  }
}

Example 3: Combined Storage​

Use both storage_keys and persistent_keys together:

{
  "version": 1,
  "storage_keys": {
    "session": {
      "sessionId": "abc123xyz"
    }
  },
  "persistent_keys": {
    "user": {
      "userId": "user_12345",
      "environment": "production"
    }
  }
}

In this example, the sessionId will be cleared on app restart, but userId and environment will persist across sessions.

Advanced Use Case: Dynamic User Data with Endpoint Tags​

You can combine the Context Setter Plugin's runtime URL parameter with the observe_storage endpoint tag to automatically fetch and update user account data based on authentication state changes.

How It Works​

This approach uses two features together:

  1. Runtime URL Parameter: Configure an additional URL on the Context Setter Plugin that will be fetched after the application loads (and access tokens are refreshed)
  2. Endpoint Tag observe_storage: Add this tag to the endpoint to make it observe all context keys it uses and automatically reload when any of those keys are updated

Configuration Steps​

  1. Configure the Runtime URL: Set up your Context Setter Plugin with a URL endpoint that returns user account data (similar to the regular startup Remote URL format shown in the examples above)

  2. Create an Endpoint with observe_storage tag:

    • Create an endpoint in Zapp that matches your runtime URL
    • Add necessary context keys (like access tokens) that will be injected into the request
    • Add the observe_storage tag to the endpoint configuration

  3. Handle Authentication State Changes: The endpoint will automatically reload when observed context keys change (e.g., when a user logs in, logs out, or modifies their profile)

Example Scenario​

When a user logs in:

  • Access token is stored as a context key
  • The observe_storage tag detects the token change
  • The Context Setter Plugin automatically re-fetches the runtime URL with the new token
  • User account data is populated in storage

When a user logs out:

  • Access token is cleared from context keys
  • The observe_storage tag detects the token removal
  • The runtime URL is fetched again (without a token)
  • Your backend should return the same keys with null values to purge the user data from storage

Example response for logged-out state:

{
  "version": 1,
  "persistent_keys": {
    "user": {
      "userId": null,
      "userName": null,
      "email": null
    }
  }
}
tip

This pattern works with feeds on screens, the Remote Context Setter Plugin, and Storefront. You can also use it to build features like dynamic tabs or filters by combining the observe_storage tag with actions that write to storage or screen state.

note

Some reserved namespace names automatically purge data from local storage on logout, but it's recommended to explicitly return null values for all user-related keys to ensure clean state management.

Errors​

In case of an error, the backend should return the following error:

  • status (number): the HTTP status code of the error response.
  • message (string): a human-readable error message.

Example error message:

{
  "status": 400,
  "message": "Invalid query parameter."
}
info

The provided context keys will override any existing context keys currently stored in the app. For storage_keys, this happens each time the API is called. For persistent_keys, the values are overwritten in persistent storage and will remain until the next update or until the app data is cleared.