Import User Traits

In addition to sending a users’ traits via the PyzeIdentity class (See for iOS and Android) , Pyze allows upload of custom user traits data, for example the date of birth, gender or a subscription level of an user. A CSV file can be uploaded via SFTP using key-based authentication.

This user data can then be used in various features e.g. Intelligence Explorer, within the Pyze platform for further correlation and analysis.

Guidelines

CSV Format

First Row of your CSV must include the names of the fields you wish to create. The first column must be “User Identifier”. Field names are case insensitive

Data Types

Pyze is typically data-agnostic, and most data is treated as a string until processed. The Pyze UI will prompt for formatting specifications for fields such as dates.

Quoting

Text may be quoted or not. Unclosed quotes will cause processing failure for that record. Commas inside unquoted strings may cause a failure for that record, it is typically advised to quote any longer strings.

File Size

SFTP uploads are essentially unlimited, but may need special handling for files > 1GB.

Contact Pyze Support for help with this.

Notes

  • App User traits are tied to an app specific “User Id” which may or may not currently exist within the Pyze system.
  • Traits are limited to data that can be represented by Unicode or ASCII text only, e.g. images are disallowed.
  • App User traits are limited to 300KB per user imported
  • User Identifier may not be larger than 128 characters or bytes
  • Processing of larger files may take extra time

Example

"User Identifier", Gender, "Subscription Status", "Subscription Date", "Field Notes"
GH-123, F, Premium, 2016-12-14, "This customer is great"
GH-484, M, Standard, 2016-01-01, "New Years Resolution"
GH-1890, F, None, , "Not yet signed up"

Posting Events From Server to Pyze

Enterprise customers can also post event data to Pyze from their backend using a RESTful API.

The Pyze Enterprise Events API allows you to send events from your servers along with the data from your mobile and web apps. You can send these events at the same speed as the Pyze SDK’s and with the same level of detail.

The Pyze Enterprise Events API accepts HTTPS POST events authenticated using HTTP Basic Authentication using an API Key/Secret generated per mobile or web app. You can attach any custom attribute data to an event, and use this data throughout the Pyze system as attributes to filter and understand your users.

Endpoint

The url for all transactions is: https://e.pyze.com/api/enterprise/server-import/events

Content-Type HTTP Header should be application/json

Authentication

The Pyze Enterprise Events API uses Basic Access Authentication headers. You can find your application’s API key and secret by navigating to the “API Keys” section of the App Profile in growth.pyze.com

Data Format

The Pyze Enterprise Events API accepts standard JSON documents with the following fields

Field Required Format Description
pyzeAppKey Yes String Your application’s Pyze App Key
Example: Act75oocQxiFzUAjeENW9A
eventName Yes String The name of this event
Example: Subscription_Purchased
userId Yes String Your custom string that identifies this specific user. The same User Identifier should be used within the Pyze SDK’s for this event to be properly attributed to that user
Example: GH-1235
eventTime Optional String (epoch) The time that this event occurred formatted as (UTC) milliseconds since epoch. If not provided, Pyze will use the time this event arrives at the server.
Example: 1481444255513
messageId Optional String (UUID) UUID that uniquely identifies this event request to ensure that each event is processed exactly once. This should should be randomly generated. If not provided, Pyze will generate a random messageId at the server.

UUIDs must be a version 4 UUID 36 characters in length and contain only hex characters and dashes (0-9, a-f, A-F, -).

Example: 7102810b-8848-44ca-8301-6b0702dfc22e
ip Optional String Your customer’s IP address. If this is not included, the IP address in the HTTP headers will be used.
Example: 123.123.123.12
attributes Optional String String of key-value pairs to attach to this event.
Example:
“Custom_key”: “Any value”,
“Custom_key2”: “Any value2”

Response

The Pyze Enterprise Events API will return a 202 response code if your event was properly formatted and accepted. The api will only validate if the overall format and validity of the JSON object, and if the request was properly Authenticated

202 Event has been accepted for processing
400 Not a valid input / “FieldName” is not provided
401 Not authorized to view
403 Need access to the provided app
500 Pyze internal server error. Please contact Pyze if problem persist

Example

A Curl Example:

curl -X POST -H "Content-Type: application/json" -u "api_key:secret" -d '{
                "pyzeAppKey" : "tKxuJDvwRV6944kz3GosUw",
                "userId" : "GH-123",
                "eventName" : "My_Custom_event",
                "messageId" : "97176608-4587-11e7-a919-92ebcb67fe33",
                "ip" : "123.345.123.135",
                "eventTime": "1496177028000",
                "Custom_key" : "Any value",
                "Custom_key2": "Any value2"
                }' "https://e.pyze.com/api/enterprise/server-import/events"

Creating Apps Programmatically

Endpoint for bulk app creation

To create Apps Programmatically via an API, use the following endpoint. This endpoint is available to Pyze Enterprise Customers.

endpoint: https://e.pyze.com/api/apps
Request Type: POST
Content-Type: applicaiton/json
Authorization: HTTP Basic Authentication
JSON payload:  {
  "platform": "iOS",
  "appname": "My Awesome App",
  "appgroupids" : ["Uy1tWo8FQ7WvNMSrMf2a6A","Tz1tWo8FQ7WvNMSrMf2a6A"]
  "timezone": "America/Los_Angeles",
}

JSON payload Legend

  • “platform” is of string type and examples include: “iOS”, “Android”, “tvOS”, “Web”, “watchOS”
  • “appname” is of string type and is the name of your app
  • “appgroupids” is an optional array of App Group IDs, each of string type. You create App Groups at growth.pyze.com. Each App Group is associated with a unique appgroupid. “appgroupids” is optional and you can exclude it completely from the payload or specify as an empty array “appgroupids” : []
  • “timezone” is of string type and examples include “America/Los_Angeles”, “Asia/Kolkata” etc. It should be a valid timezone city name. Please see here for the Zone names (TZ) you can use.

Key and Secret

To locate your key and secret, please log in to growth.pyze.com and click on “Menu” from the main Portfolio screen.

Select API keys and secret.

Generate Key and Secret

Copy Key and Secret

CURL request example

For CURL, use your key and secret separated by a “:” to generate the basic authentication string. For example, if your key and secret are as follows,

  • Key: e5f2b490-9fbf-4bb2-91df-6105cf4c871b
  • Secret: 257040a4-998b-4379-8239-0977972c2a17

You can use a base 64 encoder to encode <key>:<Secret>:

e5f2b490-9fbf-4bb2-91df-6105cf4c871b:257040a4-998b-4379-8239-0977972c2a17

into a base64 basic authentication string:

ZTVmMmI0OTAtOWZiZi00YmIyLTkxZGYtNjEwNWNmNGM4NzFiOjI1NzA0MGE0LTk5OGItNDM3OS04MjM5LTA5Nzc5NzJjMmExNw== for use in a CURL request.

curl --request POST \
  --url https://e.pyze.com/api/apps \
  --header 'authorization: Basic ZTVmMmI0OTAtOWZiZi00YmIyLTkxZGYtNjEwNWNmNGM4NzFiOjI1NzA0MGE0LTk5OGItNDM3OS04MjM5LTA5Nzc5NzJjMmExNw==' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{"platform":"iOS","appname":"Application Name","timezone":"America/Los_Angeles"}'

Analytics Reporting API

Report API

  • Endpoint : https://api.pyze.com/report/getAnalytics
  • Authentication : Auth0 URL
  • Content-Type: Application/JSON
  • Rate Limits : As Applicable per customer

Request Format:

{
  "pyzeAppKey" : string,
  "appGroupId" : string,
  "startTime" : string,
  "endTime" : string,
  "metric" :  string, 
  "aggregation" : string, 
  "filter" : string, 
  "timeType" : enum(TimeType),
}

Sample Response:

Sample Response for Activations (Metric) during the 3rd Session (Metric Filter) in the app aggregated by the os_version (Aggregation)

{
   "result":{
      "metric" : "activations",
      "aggregation" : "os_version",
      "filter" : "session_3rd",
      "metric-aggregation":[
         {
            "k":"Android 6.x",
            "v":[
               {
                  "k":"1506297600000",
                  "count":1
               },
               {
                  "k":"1506902400000",
                  "count":4
               }
            ]
         },
         {
            "k":"Mac OS X (iPhone)",
            "v":[
               {
                  "k":"1505692800000",
                  "v":1
               },
               {
                  "k":"1506902400000",
                  "v":2
               }
            ]
         }
      ]
   }
}

Error/Status codes:

  • 200 Request succeded
  • 400 Not a valid input / “FieldName” is not provided
  • 401 Not authorized to view
  • 403 Need access to the provided app/appgroup
  • 500 Pyze internal server error. Please contact Pyze if problem persists

Additional notes

  • Reports will be presented in GMT epoch
  • Only a valid combination of filter can be queried with a certain metric.

Fields, Types and Conditions

Field Type Conditions
pyzeAppKey String Either pyzeAppKey or appGroupId is required. If both are present appGrouId will take precedence
appGroupId String Either pyzeAppKey or appGroupId is required. If both are present appGrouId will take precedence
startTime String Required : UTC milliseconds since epoch. Eg: 1513393084000 - based on the GMT timezone . If start and end time are not specified , will default to last 7 days
endTime String Required : UTC milliseconds since epoch. Eg: 1513393084000 - based on the GMT timezone . If start and end time are not specified , will default to last 7 days
timeType String enum TimeType(DAY , WEEK, MONTH). Will Default to DAY
metric String Required e.g.: Installs, Activations
aggregation String Optional Eg: Carrier, Browser
filter String Metric or Aggregation filter e.g.: activations:session_3rd (metric filter) or browser:chrome (aggregation filter)

Available Metrics, Aggregations and Filters

Metric Aggregation Metric Filter
installs Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
activations Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
session_3rd
session_5th
session_10th
first_time_app_used_for_2_days_in_last_7_day_period
first_time_app_used_for_3_days_in_last_7_day_period
first_time_app_used_for_3_unique_days
first_time_app_used_for_5_unique_days
first_time_app_used_for_7_unique_days
aggregate_usage_exceeds_15_min
aggregate_usage_exceeds_30_min
aggregate_usage_exceeds_60_min
previous_consecutive_3_day_usage_exceeds_5_min
previous_consecutive_3_day_usage_exceeds_10_min
previous_consecutive_3_day_usage_exceeds_15_min
previous_consecutive_3_day_usage_exceeds_30_min
previous_consecutive_5_day_usage_exceeds_5_min
previous_consecutive_5_day_usage_exceeds_10_min
previous_consecutive_5_day_usage_exceeds_15_min
previous_consecutive_5_day_usage_exceeds_30_min
previous_consecutive_7_day_usage_exceeds_5_min
previous_consecutive_7_day_usage_exceeds_10_min
previous_consecutive_7_day_usage_exceeds_15_min
previous_consecutive_7_day_usage_exceeds_30_min
average_daily_usage_per_device Mobile & Web Analytics
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
average_app_sessions_per_device Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
daily_active_devices Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
None
retention Mobile & Web Analytics:
device_manufacturer
device_product
device_platform
device_resolution
country
locale_language
os_version
Mobile Analytics only:
device_pixels_per_inch
cellular_capability
reachability
app_version
Web Analytics only:
browser
utm_campaign
utm_medium
utm_source
cookie
browser_plugin
d1_retained
d2_retained
d3_retained
d4_retained
d5_retained
d6_retained
d7_retained
d8_retained
d9_retained
d10_retained
d11_retained
d12_retained
d14_retained
d30_retained
event_occurance None Event Name configured in the app along with Pyze generated events
event_popularity None None
event_attribute_popularity Pyze Attributes
device_manufacturer
device_product
device_platform
device_display_inches
device_display_pixel_HxW
carrier
os_version
locale_region
locale_language
locale_calendar.
Application Attributes
Event Name configured in the app along with Pyze generated events
engagement_to_interaction_app_screen None None
interactions None None