Follow

Logs API for In-app Messages

Logs API for In-App Messages

This REST API enables you to download records that contain information about the status of an in-app message that Kahuna tried to deliver to your app. An in-app message is a notification that Kahuna sends when it detects that a user has your app open or is signed into your website. Together with information about the user who received the message (the target user) and the message itself, a log record contains information about what happened when Kahuna tried to send the message.

A single in-app message might lead to multiple log records. For example, Kahuna might write one record indicating that an in-app message was sent, followed by a second record indicating that the app received the message.

Note: Although you set up in-app messages as part of a campaign you define, Kahuna only sends in-app messages in response to an API call in your mobile app. Because you can only send this call while your app is running, users usually see the message before they leave your app. Your app code has to determine how to handle in-app messages that arrive when your app is not in the foreground. The Kahuna SDK does not handle this situation automatically.

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" : [ "inapp" ]
}

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.

inapp

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 format of the individual record is:

action

The event for which the system created the log record. The possible values are:

ia_available—the server made the message available but the user has to open the app before it is delivered.

ia_delivered—the user ran the app after the server made the message available. The SDK does not confirm that the message displayed. You can send an event to confirm the display of the message.

ia_goal—the user took an action that was a campaign goal.

precomplete—before the server delivered the in-app message, the user had already taken an action that was a campaign goal. The server does not deliver the in-app message.

action_detail

Provides more detailed information about the event described in the action field. The value depends on the value of action:

For "action" : "ia_available", the field is not present.

For "action" : "ia_delivered", the field is not present.

For "action" : "ia_goal", the value is an identifier for the goal the user achieved after receiving the in-app message.

For "action" : "precomplete", the value is an identifier for the goal the user achieved before the server delivered the message.

user_id

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

credentials

A list of user credentials that identify the target user. All of the available user credentials for the user who was the target of the in-app message.

campaign

The name of the campaign that issued this in-app message. When you look at your campaigns in the Dashboard, this is the name that is displayed for the campaign associated with the in-app message.

campaign_id

The Kahuna internal ID for the campaign message.

message

The in-app message. The value depends on the value of action: For ia_available and ia_delivered, the value is the in-app message sent to the user. For precomplete and ia_goal, this field is not present.

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 the first part of the response body.

{
"more_records": true,
"cursor": "_NJXWEX2WGZBS24KQJNMEMM2XIN2GSRTFGFGGS2KTMJYWWNCGIE______
        _INEUGUSCIFCUCUKBINJFKQSBJFBESSKBKVEUMUKWLFFVCPJ5HU6Q____",
"inapp": [
    {
        ...

The following JSON snippet shows an example of the records in a response.

"inapp": [
        {
         "user_id": 162860001,
         "campaign": "startios Trigger In-App",         
         "timestamp": "2016-06-01 23:41:24.731020",
         "campaign_id": 85440012,
         "action": "ia_available",
         "message": "test{{birth_year|default:\"gh\"}}"
       },
         {
          "user_id": 164838001,
          "campaign": "Individual Reachout",            
          "timestamp": "2016-06-01 23:41:24.731020",
          "campaign_id": 7610011,
          "action": "ia_available",
          "message": "test{{last_name|default:\"fsdf\"}}"
       }
   ]
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments