Follow

User/Campaign API

User/Campaign API

This REST API provides a list of users targeted by Kahuna campaigns. Use this API to determine which users a Kahuna campaign reached, which campaign-related actions users performed, or which email messages a Kahuna Experience contains. You can narrow this list by including in your request a date range, campaign, or campaign-related action.

For example, to know which users in a push campaign became more engaged last month, call this API to get a list of user records over the last month that contain the campaign name and the more engaged action.

You can use this API to get campaign-related data for up to 100 credentialed users. Each record in the response includes all campaign-related data for that user.

This API also provides a listing of Kahuna Experience email messages. Call this API with only the experience name, and it returns a list containing the experience's email message titles and subject lines.

API Request

Request URI and Header

Request URI - HTTP POST

 

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

Note: Targeting the sandbox environment is not currently supported.

 

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 either an encoded cursor or a campaign name, time range, and a list of user credentials. The JSON is also known as a request object. The fields and possible values of the request object are described below.

Fields
cursor

An encoded cursor provided in the response by this API to indicate more records are available. To return more records, copy this cursor and paste it into a new call (see cursor). Continue making cursor calls until the response is complete (see more_records).

suite_id Specifies an ID for the campaign suite associated with this user request (a campaign suite label).
group_id Specifies an ID for the campaign group associated with this user request (a campaign group label).
campaign_name

Specifies a name for the campaign suite or group associated with this user request (a campaign suite or group label).

experience_id Specifies the ID for the experience associated with this user request.
experience_name Specifies the name for the experience associated with this user request.
action_list

Optional.

The list of actions to include in the request. The API response returns a list of records of the requested actions. The action_list field has the following subfields:

scheduled – Messages scheduled to be delivered.

delivered – Messages delivered.

delivery_failed – Messages failed to be delivered, usually due to uninstalls shortly before or after Kahuna message delivery attempts.

more_engaged – Records of users becoming more engaged.

goal_achieved – Records of users achieving their goals.

push_clicked – Push messages tapped or clicked.

email_opened – Email messages opened.

email_clicked – Email links clicked. Does not include email unsubscribes.

spam_report – Messages reported as spam.

unsub – Email messages resulting in an unsubscribe response.

available – Records of in-app messages that were made available.

inapp_displayed – In-app messages displayed within an application.

inapp_clicked – In-app messages clicked or tapped, but not dismissed.

inapp_dismissed – In-app messages closed without a response.

added_to_custom_audience – Additions to the Facebook custom audience.

from_utc

The beginning of the time range of interest, specified in seconds from the POSIX Epoch in UTC time. If from_utc is specified, to_utc is optional.

to_utc

The end of the time range of interest, specified in seconds from the POSIX Epoch in UTC time. If to_utc is specified, from_utc must also be specified and must be less than to_utc.

exclude_unnecessary_ghost

If set to true, the results do not include ghost push messages sent to determine whether the user has uninstalled the application. Otherwise, the export will include these ghost push messages.

users

The user credentials for your request. See the examples below.

Example
{
   "campaign_name": "Test_Campaign",
   "action_list": [
      "delivered",
      "more_engaged",
      "goal_achieved"
   ],
   "from_utc": 1482681600,
   "to_utc": 1483257600,
   "exclude_unnecessary_ghost": true,
   "users": [
      {
         "username": "user1",
         "email": "user1@company1.com"
      },
      {
         "username": "user2",
         "email": "user2@company2.com"
      }
   ]
}

API Response

The response to a Push API request consists of an HTTP response code and a response body.

HTTP Response Codes
Codes
200

The request was parsed and validated.

400 The request cannot be parsed. Invalid request.
401

Authentication failed. You did not specify authentication, you specified your credentials incorrectly, or authentication is denied.

409 Your credentials are not authorized to use the User/Campaign API.
500 Internal server error.
Response Body

The response body is either a list of users matching the provided campaign or group and user credentials. Every 50 seconds, the request times out if it has not yet processed all of the user credentials in the request.

Fields
rows

Returns the resulting users of the user/campaign request, using the following syntax:

[{<result_1>}, {<result_2>}, ...]
cursor

If the request times out after 50 seconds, an encoded cursor is returned.

For the remaining results, submit requests with a cursor call until all rows have been returned. For example:

{
"cursor": "_NJXWEX3PJQZUCNCCKQ3TGOLGORBXU33CGZUXCRDDMJAWQ6KYOM___
           ___-BHNI2T3MLEAQAAASA4EAAEEAQCAAKGQGBCIE4EEQJYQLBLQV"
}
more_records

A value of true indicates that the request has timed out after 50 seconds; however, the request continues to retry until all rows have been returned. A value of false indicates that all rows have been returned; the response is complete.

For successful requests, the folowing is a glossary of the actions and reasons that may be returned:

Actions: 

  • inapp_clicked: The "positive" (not just dismissed) button was clicked in the in-app message.
  • goal_achieved: The user performed one of the goals of the campaign (primary or tracking) after receiving the message and within the attribution timeframe.
  • delivery_failed: The message was not delivered. The reason property has more information.
  • available: An in-app message was made available. This means we are now waiting for the user to launch the app so we can deliver.
  • inapp_dismissed: The "negative" button was clicked in the in-app message.
  • push_clicked: The user tapped on the push message, taking them to the app.
  • scheduled: The message was scheduled in Kahuna's system. For most campaign types scheduled is closely followed by delivered/delivery_failed. However some campaign types may schedule well in advance of the intended delivery time.
  • more_engaged: The user opened the app after receiving the message within the engagement timeframe.
  • delivered: The message was delivered to the user.
  • inapp_not_displayed: The in-app message was delivered to the app but was not displayed. This can happen if we deliver an in-app but the user has closed the app and when they finally open it again the in-app may have expired.
  • inapp_displayed: The in-app message was displayed to the user
Reasons:
  • precomplete: Applies to delivery_failed for Conversion campaigns. Precomplete means the user already completed the conversion goal before we were going to send the message. We call that an organic conversion.
  • duplicate_ghost_push: Delivery_failed for a ghost push. For effiency on our end we don't send two ghost pushes in a row.
  • original_push_blocked: Delivery_failed for ghost push. Whenever we schedule a push we also schedule a ghost push to be sent later. At the time we try to send the ghost, we check if the original push was sent successfully. If not, we don't send the ghost.
  • blocked: Delivery_failed for ghost push or email. For push this indicates we already found a previous_uninstall or campaign_uninstall but had another push scheduled.
  • previous_uninstall: Delivery_failed for push. The push was not send because the user had already uninstalled the app.
  • campaign_uninstall: Delivery_failed for ghost push. The original push was delivered, but when trying to send the corresponding ghost push, we discovered the user had uninstalled. In this case we attribute the uninstall to the message as a negative action.
  • no_longer_valid: Delivery_failed for any campaign. Either the campaign had been disabled or the user did not match the filter criteria at the time we were to deliver.
  • missing:push_token: Delivery_failed for push. At the time we were to deliver we did not have a push token.
  • rate_limited: Delivery_failed for any campaign. A message was not delivered because a previous message on the same channel was sent within the configured cooldown time.
  • campaign_opt_out: Delivery_failed for ghost push. The original push was delivered, however when we were to deliver the ghost push we discovered the user had opted out of push. In this case we attribute the opt-out as a negative action to the message.
  • unrecoverable_error: Delivery_failed for any campaign. Usually this is an error on the provider end (GCM/FCM, APNS) from which we cannot retry/recover.

 

Example

The following JSON snippets show a valid request and a single record from the valid user/campaign response object. Note that the record for user John Doe is returned with the property more_engaged for the field action.

{
{
   "action_list": [
      "delivered",
      "more_engaged",
      "goal_achieved"
   ]
}
                }
{
"control": false,
"global_control": false,
"campaign_id": 7159750106,
"last_gplus_id": null,
"push_token": null,
"last_user_id": null,
"last_email": "john.doe@gmail.com",
"goal": null,
"last_linkedin_id": null,
"merged_from_kahuna_user_id": null,
"platform": null,
"experience_id": null,
"send_id": "4839779942593216",
"channel": "email",
"count": null,
"receiver_id": null,
"timestamp": "2016-12-31 00:37:08",
"reason": null,
"suite_id": 481352001,
"kahuna_user_id": 6459071425,
"ghost": false,
"last_facebook_id": null,
"last_username": "john.doe@gmail.com",
"url": null,
"original_send_id": null,
"last_twitter_id": null,
"value": null,
"message_id": 7177661044,
"group_display_name": "New Year's Note from Sameer",
"action": "more_engaged",
"tracked_goals": null,
"group_id": 7184631035
}

The following JSON snippets show an invalid user/campaign request object and its corresponding response object.

{
   "campaign_name": "Wrong_Campaign",
   "suite_id": 481352001,
   "group_id": 7184631035,
   "action_list": [
      "delivered",
      "more_engaged",
      "goal_achieved"
   ],
   "from_utc": 1482681600,
   "to_utc": 1483257600,
   "users": [
      {
         "username": "john",
         "email": "john@kahuna.com"
      },
      {
         "username": "jane",
         "email": "jane@kahuna.com"
      }
   ]
}

The invalid request object generates the following response object.

{
   "error_detail": "Requested campaign not found",
   "error_code": 400,
   "success": false,
   "error": "The request could not be parsed"
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments