Get Interpretable Values with the Metadata API
The Monetate Metadata API allows you to retrieve interpretable values for experiences, page events, and custom targets. Monetate provides unique IDs because they never change, whereas you can change the name of experience variants and page events in the platform. You can send a request to the API with an experience ID, page event ID, or target ID to return a set of interpretable values.
Your application must identify itself every time it sends a request to the Monetate Metadata API. The Monetate Auth API allows you to manage tokens on a per-user key basis. With this API, you can request a token that has a fixed expiration, that is associated with a public key you uploaded to Monetate, and that may be revoked by deactivating that key.
The following example script, in version 3 of Python, demonstrates how to look up metadata for unique IDs found in Session Stream.
Python
1# coding: utf-8
2
3from collections import Counter
4
5import json
6
7import jwt
8
9import requests
10
11import time
12
13# We have here a sample session data file. You can download one following the documentation for Session Stream.
14
15with open('one_hour.json', 'r') as f:
16 raw_data = f.read()
17
18sessions = [json.loads(line) for line in raw_data.splitlines()]
19
20# The session data in this file refers to objects in the platform like experiences, page events, and targets by ID. This means your data from Session Stream remains consistent regardless of name changes in the UI.
21# But to review this data, we want to turn these IDs into human-interpretable names. The Metadata API is the way to fetch those mappings.
22# Metadata API requires authentication. Let's first get an auth token.
23# - Send a GET request to the refresh endpoint with an 'Authorization' header.
24# - The value of the header must be 'JWT <token>' where <token> is an encoded JWT token as defined by RFC 7519.
25# - The token's payload must contain an 'iat' claim and a 'username' claim.
26# - The 'iat' claim must contain a Unix timestamp of when the request is sent. A leeway of 60 seconds is allowed for client clock skew.
27# - The API username used for the 'username' claim must have a public key configured in the UI (on the API Keys tab of the Sites page in the settings)
28# - The private key used to encode the JWT token must be the matching private key for the aforementioned public key.
29
30# Create the payload. In the 'username' claim, use the username that is generated by the API Keys on the Sites page of the UI settings.
31
32payload = {'iat': int(time.time()), 'username': 'api-111-demo'}
33
34# Load up your private key and use it to encode the payload. We allow RS256, RS384, and RS512 as encoding algorithms.
35
36with open('private.pem', 'r') as f:
37 private_key = f.read()
38
39jwt_token = jwt.encode(payload, private_key, algorithm='RS256')
40
41# Assemble and send the request to the auth endpoint.
42# The default TTL for the returned auth token is 3600 seconds (1 hour).
43
44# You may optionally send a 'ttl' query parameter to request a specific TTL in seconds, between 600 (15 minutes) to 43200 (12 hours).
45
46AUTH_REFRESH_URL = 'https://api.monetate.net/api/auth/v0/refresh/'
47
48resp = requests.get(AUTH_REFRESH_URL,
49 headers = {'Authorization': 'JWT {}'.format(jwt_token)})
50
51# Grab the token from the response. Note that the response also contains an expiration timestamp so you can automate preemptive refreshing of tokens.
52
53auth_token = resp.json()['data']['token']
54
55# Now that we have a token, we can use it to access the Metadata API.
56# Replace "example" with your retailer shortname found in the base URL of your API documentation.
57
58METADATA_BASE_URL = \
59 'https://api.monetate.net/api/metadata/v1/example/production/metadata/'
60
61PAGE_EVENT_URL = METADATA_BASE_URL + 'pageevent/'
62
63VARIANT_URL = METADATA_BASE_URL + 'variant/'
64
65TARGET_URL = METADATA_BASE_URL + 'customtarget/'
66
67# Let's go ahead and fetch a bunch of page events. 1000 is the maximum allowed in one request.
68# These are paginated, so you can make smaller requests and piece them together later.
69
70page_event_resp = requests.get(PAGE_EVENT_URL,
71 headers = {'Authorization': 'Token {}'.format(auth_token)},
72 params = {'page_size': 1000})
73
74# Grab the list of events. Make it a dict so we can reference by ID.
75
76page_event_list = page_event_resp.json()['data']
77
78page_event_data = {d['id']: d for d in page_event_list}
79
80# Now let's marry this data to your session data from earlier.
81# Session data has a property page_event_ids which is a dict of page event IDs -> the time at which the event occured.
82# These page event IDs are the same ones retrieved in the last Metadata API response.
83# Let's loop over the sessions and print the city the user browsed in and triggered page events for the session.
84
85missing_page_events = []
86
87for session_data in sessions:
88 city = session_data['city']
89 session_page_events = []
90
91 for event_id in session_data['page_event_ids']:
92
93# We'll need to coerce the IDs back into ints since JSON forces dict keys to be strings.
94
95 try:
96 page_event_metadata = page_event_data[int(event_id)]
97
98# Let's grab the title
99
100 session_page_events.append(page_event_metadata['title'])
101 except KeyError:
102 missing_page_events.append(event_id)
103
104print('A user in {} triggered the following page events: {}'.format(city, session_page_events))
105
106print('{} page events could not be matched; do you need to request more page event definitions from the Metadata API?'.format(Counter(missing_page_events)))
107
108# Now let's grab experience data. Here, we'll also show how to do some simple pagination.
109
110has_next = True
111
112variant_list = []
113
114page = 1
115
116while has_next:
117 variant_resp = requests.get(VARIANT_URL,
118 headers = {'Authorization': 'Token {}'.format(auth_token)},
119 params = {'page_size': 1000, 'page': page})
120
121 parsed_response = variant_resp.json()
122
123# Grab the list of experiences from this page.
124
125 variant_list.extend(parsed_response['data'])
126
127# Are there more pages to fetch?
128
129 if parsed_response['meta'].get('next', None):
130 page = page + 1
131 else:
132 has_next = False
133
134# Make it a dict so we can reference by ID.
135
136variant_data = {e['id']: e for e in variant_list}
137
138# offer_ids in our session data contain experience IDs, which we've just fetched definitions for from the Metadata API.
139# We'll do a simple counter to see what experiences were seen in the given day's worth of data.
140
141experiences_shown = []
142
143for session in sessions:
144
145 for offer_id in session['offers']:
146
147# Offer IDs have an extra piece at the end indicating the variant, which you'll want to discard for our current purpose.
148
149 experience_id = offer_id.split('-')[0]
150
151experiences_shown.append(experience_id)
152
153experience_counter = Counter(experiences_shown)
154
155# Now we can put the two together. Let's take the top 10 most seen experiences and display their information:
156
157top_10 = experience_counter.most_common(10)
158
159for experience_id, count in top_10:
160
161 print("{} was seen by {} sessions.".format(variant_data[experience_id]['experience_name'], count))
162
163# Let's also fetch custom target metadata. Simply follow the same pattern.
164
165target_resp = requests.get(TARGET_URL,
166 headers = {'Authorization': 'Token {}'.format(auth_token)},
167 params = {'page_size': 1000})
168
169# Grab the list of targets.
170
171target_list = page_event_resp.json()['data']
172
173# Now let's make it a dict so we can reference by ID.
174
175target_data = {d['id']: d for d in target_list}
176
177# The above dict is keyed on custom target IDs, which are present as keys in the custom_targets dict on each session row.
178# You can marry the two just like we did above to do any of your own analytics.