Follow

Logs API for Push

Logs API for Push

This REST API enables you to download records with information about the status of a push notification that Kahuna tried to send to a user.

A single push to a single user can result in more than one log record. For example, if the campaign sends a push notification to a user, then Kahuna detects that the user completed a goal of the campaign, Kahuna logs a push action followed by a goal action.

API Request

Request URI and Header

Request URI - HTTP POST

To target the production environment: https://tap-nexus.appspot.com/api/kahunalogs?env=p

To target the sandbox environment: https://tap-nexus.appspot.com/api/kahunalogs?env=s

Request Header

Content-Type: application/json

Authorization: The API uses Basic Authentication (BasicAuth), which requires credentials in the form of a username (Secret Key) and password (API Key).

The Secret Key and API Key for the namespace are:

Secret Key: Available in Settings
API Key: Available in Settings
Request Body

The request body contains data that controls which log records the server returns. The fields are described below.

Fields
timestamp

Note: You must specify either timestamp or cursor; otherwise, the server returns a 400 HTTP response code.

The server returns records for the date specified in the timestamp. For this date, the returned records have a timestamp starting at the specified time and ending on or before 23:59:59 of the specified date. Although most known date and time formats work, you can always use the format:

m/dd/yyyy h:mm

Elements in bold are entered exactly as written.

  • m is the month number (1 or 2 digits)
  • d is the day number (1 or 2 digits)
  • yyyy is the four-digit year
  • h is the hour in 12-hour format
  • mm is minute

You must convert the time to its UTC equivalent. All Kahuna timestamps are stored in UTC. The API does not convert the timestamp value to UTC before comparing it to log records.

cursor

Note: You must specify either timestamp or cursor; otherwise, the server returns a 400 HTTP response code.

This is the identifier of a previously returned cursor. Cursor identifiers are temporary and can expire at any time. See Response Body, below.

number_of_records Required. The number of records to retrieve. The number must be greater than 0 and less than or equal to 1000.
categories_to_return

Required.

For email logs, set "categories_to_return" : ["email"]

For push logs, set "categories_to_return" : ["push"]

For in-app messages, set "categories_to_return" : ["inapp"]

For user merge logs, set "categories_to_return": ["user_merge"].

You can retrieve other categories except for user_merge in the same request by adding their categories to the array. However, you cannot combine the user_merge category with other categories.

Example
{
    "number_of_records" : 1000,
    "timestamp" : "07/30/2016 00:00",
    "categories_to_return" : [ "push" ]
}

API Response

Kahuna responds to a logs request with a numeric code and a response body.

HTTP Response Codes

The HTTP response code returned from a request indicates the overall status of the request.

Codes
200 Successful API call.
400

Bad request. Some part of the request is malformed. For example, the specified number of records is invalid.

401

Authentication or authorization failure. The credentials supplied with the request are invalid.

409 Not authorized. The credentials are not authorized to use the Logs API.
500 Kahuna internal server error.
Response Body

The response body is a JSON object that contains additional information about the status of the request, as well as an array of log records. If the server cannot deliver all the records that match your request in a single response, the response body contains two fields in addition to the array of log records:

  • more_records is a boolean value that is set to true if more records are on the server.
  • cursor is a string value that points to the set of remaining records.

To continue retrieving records for your original request, add the value of cursor in the request body and send a new request. The server responds with a new set of records. This process continues until one of these conditions is met:

  • The server has sent all the records that match the day you specified in the timestamp field in the request body.
  • The number of records sent is equal to the value of number_of_records you specified in the request body.
  • You stop sending log requests containing the value of cursor returned to you in the response body.

The fields in the response body and individual log records are listed below.

Fields
success

If the request fails, this field is set to false. If the request succeeds, this field is not present.

error

If an error occurs, provides a human-readable error message. If no error occurs, this field is not present.

error_code

If an error occurs, provides the HTTP error code. If no error occurs, this field is not present.

error_detail

If an error occurs, provides more detailed information about the error. If no error occurs, this field is not present.

more_records

If more records are available for download this field is set to true; otherwise the field is set to false.

cursor

If the server cannot deliver all the records that match your request in its initial response, it sets more_records to true and returns a cursor value that points to more records on the server. To retrieve these records, move the value of cursor to the cursor field in the request body and re-issue the request.

push

An array of JSON objects representing the log records. If the request is well-formed, but no records match the time and date criteria, the array is empty. The number of fields in each record object vary, depending on the push event represented by the object.

action

The reason for creating the log record. The possible values are:

push Kahuna sent a push notification to a device.
goal After Kahuna detected that the user received a push notification, the user took some action that met a goal for the campaign associated with the push.
click The user clicked on the notification.
more engaged After the push notification, the user reopened the app.
precomplete The user took action that led to a campaign goal before Kahuna sent the push, so the push was not sent.
rate_limited The cooldown period had not expired when the system tried to send a push notification to the target user. For example, one campaign sends a push to a user, then 30 minutes later another campaign starts to send a push to the same user. If the cooldown period for the second campaign is 4 hours, the user is not eligible for contact. The system does not send a second push, and at the same time it records a rate_limited log record.
duplicate_ghost_push The system started to send a ghost push to a user, but determined that the previous push to the user was also a ghost push, so there is no need to send another ghost push. For this action value, the ghost flag is set to true.
uninstalled

The system tried to send a push notification to a user but the user uninstalled the app. This event can occur in the following situations:

  • The system tried to send a regular push, but the user uninstalled your app. In this case, the value of the ghost field in the log record is false. Because the user might have uninstalled your app for a variety of reasons unrelated to this or any other messages, don't assume that something is wrong with your campaign.
  • The system tried to send a ghost push, but the user uninstalled your app.

The ghost push was added to the schedule when Kahuna sent a regular push, so at that time the target user still had your app installed. If the regular push fails, Kahuna removes the ghost push for that user. If the regular push succeeds, Kahuna leaves the ghost push to go out at a later time. Later, when Kahuna sends the ghost push, it double-checks that the target user still exists. If the user is gone, the user left after Kahuna sent the regular push but before Kahuna sent the ghost push. This indicates that the target user did not like something in the regular push. The value of the ghost field in the log record is true.

missing_params

You sent a push object with the Push API and the object had an incorrect format or the system encountered an internal error. The action_detail value describes the exact problem, which can be one of the following:

  • For a push notification you created with the Push API, the message indicates the parameters that were missing or incorrectly formatted.
  • For a push notification you created with the Push API, the total size of the notification and params fields is larger than the maximum for the device. The message lists the total size.
  • The system is unable to create the push payload for the target device.
push error An internal error occurred while the system was trying to send a push notification.
unrecoverable A push certificate error occurred while the system was trying to send a push notification to an Android or iOS device. The push certificate that allows you to send notifications to these device types has expired. Contact Apple or Google to get a new certificate.
action_category

The sub-type of the event described in the action field.

action_detail

Provides more detailed information about the event described in the action field.

ghost

If this log record is for a ghost push, the value is true, otherwise the field is not present. A ghost push is a push notification that does not contain a message. Kahuna sends ghost pushes as part of process that measures the possible negative effects of a push notification. The ghost push is generated at the same time Kahuna sends the regular push, but it doesn't go out until some time later.

message

Provides information about the source of the notification. If the value of action is push, push error, missing_params, unrecoverable or rate_limited, the value of message is one of the following:

  • custom—the push was sent via Push API
  • control—the push was sent as part of the campaign's control group.
  • campaign indicator—the push was sent as part of the indicated campaign group.

If the value of action is uninstalled or duplicate_ghost_push, the value of message is unknown.

If the value of action is goal, precomplete or more engaged, message is not present.

campaign

The name of the campaign that generated this push notification message. When you look at your campaigns in the Dashboard, this is the name that is displayed for the campaign associated with the push notification.

campaign_id

The Kahuna internal ID for the campaign message. Identifies the message that was sent.

user_id

The Kahuna internal ID for the user who is the target of the push notification. Kahuna assigns this GUID when your app first connects with Kahuna even if you do not provide any credentials for the user.

dev_id

The Kahuna internal ID for the device that received the push notification. Kahuna assigns this GUID to a device when your app first connects from that device to Kahuna.

credentials

A list of user credentials that identify the target user. The target of a push is the user that Kahuna selects as a recipient of the push, based on your campaign settings (or your API data, if you use the Push API). Although Kahuna might select the user or device based on just a few credentials, this log record field contains all of the credentials associated with the user or device.

push_token

If the target device is running iOS or Android, this value is the token that allows the device to receive push notifications from Kahuna. You set up this token (with Apple or Google) when you start using Kahuna if you decide to use push notifications.

timestamp

The date and time the record was created. The format is YYYY-MM-DD HH:MM:SS.SSSSSS. The time is UTC.

os

The platform identifier for the target device. Possible values are android or ios.

Example

The following JSON snippet shows an example of a push response body.

{
 "push": [
        {
         "dev_id": "1a22222be0000006a11c1111e111d900",
         "user_id": 613800000,
         "campaign": "startios Trigger Push",           
         "timestamp": "2016-06-01 23:41:24.731020",
         "campaign_id": 81140000,
         "action": "rate_limited",
         "action_detail": "Push message will not be sent because a message has already been
                     sent to push token 'x' for campaign group/campaign 
                        'groupx'/'x' within 43200 seconds",
         "push_token": "44f3090022f56332df3de484f7d1f39fe17687b02e9d233fcad980",
         "message": "1",
         "ios"
       },
         {
          "user_id": 523811000,
          "campaign": "group78510002",          
          "timestamp": "2016-06-01 23:41:24.731020",
          "action_detail": "start ios",
          "action": "precomplete",
          "credentials": ["token:44f3090022f56332df38afc434309de4847b02e9d233fcad980"]
       }
   ]
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments