Skip to main content

Embed Account Profiles in Your Application

Zuora

Embed Account Profiles in Your Application

  1. Last updated
  2. Save as PDF

You can use iframes to display Insights account profiles in your application.

Prerequisites

Before you can display an Insights account profile in your application, you must have:

  • Obtained your Insights stream token. Submit a request at Zuora Global Support if you do not know your Insights stream token.
  • Specified an API secret in Insights settings. To specify an API secret, navigate to Settings > Embed Account Layout in Custom Application.
  • Assigned an account profile layout to be used when Insights is embedded in custom applications. See Set the Layout of Account Profile Pages for more information.

Embed an Account Profile

To display an Insights account profile in your application, load the following request URL in an iframe:

https://nw1.app.insights.zuora.com/data/embed/account/accountId?queryString

Request URL Path Parameters

accountId required ID of the account to display. For example, 2c92c0f84902517001490d6d18fc1b80. Account IDs in Insights match the account IDs in your Zuora tenant.

Request URL Query String Parameters

apiToken required Insights stream token. To obtain the token for a stream, submit a request at Zuora Global Support.
timestamp required The current time, in ISO 8601 format. For example, 2016-12-31T23:59:59Z.
userName required The user name (email) of an Insights administrator. See Add Team Members for more information about managing users in Insights.
signature required

Keyed-hash message authentication code (HMAC) for the request, in base64 format.

  • Hash function: SHA-256

  • Key: the API secret that you specified in Insights settings

  • Message:

    GET
    nw1.app.insights.zuora.com
    /data/embed/account/accountId
    qsParams

    Where:

    Parameter Description
    accountId ID of the account to display.
    qsParams

    Query string specifying the values of apiToken, timestamp, and userName. The parameters must be in alphabetical order. Each parameter value must be URL-encoded.

    For example:

    apiToken=oVCvXeqLvVGhSDWigGAoLAbQBLZYBFWO&timestamp=2016-12-31T23%3A59%3A59Z&userName=admin.user%40example.com

See Examples for an example of how to generate the HMAC.

Do not generate the HMAC in your front-end code. Anyone who knows the API secret could authenticate and access your Insights stream.

Examples

The following Python script generates the request URL for an Insights account:

import base64, hashlib, hmac, time
from collections import OrderedDict
from urllib.parse import urlencode, quote_plus

insights_server = "nw1.app.insights.zuora.com"
api_token = "your_stream_token"
api_secret = "your_api_secret"
admin_username = "admin.user@example.com"
account_id = "account_in_your_stream"

path = "/data/embed/account/%s" % account_id

url_params = {
    'userName': admin_username,
    'apiToken': api_token,
    # Add a ISO 8601 compliant timestamp (in GMT)
    'timestamp': time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
}

# Sort the URL parameters and encode them
url_string = urlencode(OrderedDict(sorted(url_params.items())))

string_to_sign = "GET\n%s\n%s\n%s" % (insights_server, path, url_string)

# Sign the request
signature = hmac.new(
key=api_secret.encode('utf-8'),
msg=string_to_sign.encode('utf-8'),
digestmod=hashlib.sha256).digest()

# Base64 encode the signature
signature = base64.encodestring(signature).strip()

# Make the signature URL safe
urlencoded_signature = quote_plus(signature)
url_string += "&signature=%s" % urlencoded_signature

request_url = "https://%s%s?%s" % (insights_server, path, url_string)

print(request_url)

For example, running this script generates the following request URL:

https://nw1.app.insights.zuora.com/data/embed/account/account_in_your_stream?apiToken=your_stream_token&timestamp=2016-12-01T00%3A50%3A28Z&userName=admin.user%40example.com&signature=RU1ce1bfF0TpeiFAr0fCMBuG9UdRx4xbaBtm%2FSG062A%3D