Treatment Management
This document provides a guide and overview for the InsertTreatment and UpdateTreatment RPCs, which allow you to insert and update treatments directly via API.
UpdateTreatment
API to update an existing treatment.
message UpdateTreatmentRequest {
// Required.
string project_id = 1;
// Required.
string treatment_id = 2;
// Optional.
string name = 3;
// Optional.
string description = 4;
// Optional.
optional TargetActionPb target_action = 15;
// Optional.
// Specifies surfaces that should be ineligible for the treatment.
// Values in removed_surfaces must exactly match surface names.
// Note: Sending an empty list would overwrite and clear removed_surfaces from this treatment.
RemovedSurfacesListPb removed_surfaces = 14;
// Required.
string last_modified_by = 5;
// Optional.
.google.protobuf.Timestamp start_timestamp = 6;
// Optional.
.google.protobuf.Timestamp end_timestamp = 7;
// Optional.
// Content of the treatment.
ContentPb content = 8;
// Optional.
// Tags to be linked to this treatment.
// Note: Sending an empty list of tags would overwrite and clear all tags from this treatment.
repeated TagPb tags = 9;
// Optional.
// Either treatment_id or external_treatment_id are required.
// External Treatment Id, that is a primary key in the customer's system.
string external_treatment_id = 10;
// Optional.
// If true, it publishes the treatments.
optional bool should_publish = 11;
// Optional.
// Note: If eligibility_rules is unset, the existing rules remain unchanged.
// If set (even as an empty list), it replaces any previously stored rules for this treatment.
optional EligibilityRulesListPb eligibility_rules = 12;
// Optional.
// Note: Sending an empty string would overwrite and clear mutual_exclusion_group
// from this treatment.
optional string mutual_exclusion_group = 13;
}
message UpdateTreatmentResponse {
TreatmentPb treatment = 1;
}
InsertTreatment
API to create a new treatment
message InsertTreatmentRequest {
// Required.
string project_id = 1;
// Required.
// Metadata of the treatment.
string name = 2;
// Required.
string description = 3;
// Optional.
optional TargetActionPb target_action = 15;
// Required.
string treatment_type_name = 4;
// Optional.
// Surfaces which should be ineligible for the treatment.
// Values in removed_surfaces must exactly match surface names.
RemovedSurfacesListPb removed_surfaces = 14;
// Required.
string last_modified_by = 5;
// Required.
// Details related to treatment launch like start time and end time of the treatment.
// Start time of the treatment.
.google.protobuf.Timestamp start_timestamp = 6;
// Optional.
// End time of the treatment. If this field is unset, treatment will never end.
.google.protobuf.Timestamp end_timestamp = 7;
// Required.
// Content of the treatment.
ContentPb content = 8;
// Optional.
// Tags to be linked to this treatment.
repeated TagPb tags = 9;
// Optional.
// External Treatment Id, that is a primary key in the customer's system.
string external_treatment_id = 10;
// Optional.
// If true, it publishes the treatments.
optional bool should_publish = 11;
// Optional.
optional EligibilityRulesListPb eligibility_rules = 12;
// Optional.
optional string mutual_exclusion_group = 13;
}
message InsertTreatmentResponse {
TreatmentPb treatment = 1;
}
Entities
Treatment
message TreatmentPb {
// Required.
string project_id = 1;
// Required.
string treatment_id = 2;
// Required.
TreatmentTypePb treatment_type = 3;
// Required.
string name = 4;
string description = 5;
// Required.
repeated TreatmentVersionPb versions = 6;
// Status of the treatment.
// Note: It's a readonly field.This value is derived from the status of the associated treatment versions.
Status status = 7;
enum Status {
STATUS_UNSPECIFIED = 0;
// If there is any version which is live and being served.
LIVE = 1;
// If there is only one version and that is in draft.
DRAFT = 2;
// If there is only one version and that is scheduled to be served in future.
SCHEDULED = 3;
// If the last LIVE version has crossed the end_timestamp of it's lifetime.
ARCHIVED = 4;
// If the treatment has been paused manually.
PAUSED = 5;
}
string last_modified_by = 8;
.google.protobuf.Timestamp last_modified_timestamp = 9;
ModificationSource modification_source = 10;
enum ModificationSource {
MODIFICATION_SOURCE_UNSPECIFIED = 0;
AUXIA_CONSOLE = 1;
API = 2;
}
// Optional.
// External Treatment Id, that is a primary key in the customer's system.
string external_treatment_id = 11;
// Optional.
optional MutualExclusionGroupPb mutual_exclusion_group = 12;
}
message TreatmentVersionPb {
// Note: It's a readonly field. Status is calculated as per the launch config details.
Status status = 1;
repeated TagPb tags = 2;
.google.protobuf.Timestamp start_timestamp = 3;
.google.protobuf.Timestamp end_timestamp = 4;
ContentPb content = 5;
enum Status {
STATUS_UNSPECIFIED = 0;
LIVE = 1;
DRAFT = 2;
SCHEDULED = 3;
ARCHIVED = 4;
}
EligibilityRulesListPb eligibility_rules = 6;
// Removed Surfaces associated with this treatment version.
RemovedSurfacesListPb removed_surfaces = 7;
TargetActionPb target_action = 8;
}
message TagPb {
string name = 1;
}
// Treatment content.
message ContentPb {
repeated ContentByLanguagePb content_by_language = 1;
repeated TreatmentContentFieldPb language_agnostic_content_fields = 2;
message ContentByLanguagePb {
LanguageCodePb language_code = 1;
repeated TreatmentContentFieldPb content_fields = 2;
}
message TreatmentContentFieldPb {
// Note: It has to be one of the fields from associated treatment type. Otherwise, error would be thrown.
string field_name = 1;
oneof field_value {
string string_value = 2;
}
}
message LanguageCodePb {
// Note: It has to be one of the supported language codes. Otherwise,error would be thrown.
string language_code = 1;
}
}
message TargetActionPb {
int64 event_id = 1;
}
message EligibilityRulesListPb {
repeated EligibilityRulePb rules = 1;
}
message MutualExclusionGroupPb {
int64 project_id = 1;
int64 mutual_exclusion_group_id = 2;
string name = 3;
}
message RemovedSurfacesListPb {
repeated SurfacePb surfaces = 1;
}
TreatmentType
// Treatment Type defines the content fields and restrictions for the treatment.
message TreatmentTypePb {
// Project ID to which this treatment type belongs to.
// Required.
string project_id = 1;
// Name of the treatment type.
// Required.
string name = 2;
// Field to specify the delivery mode of this treatment type
// Required.
DeliveryType delivery_type = 3;
// List of language specific content fields.
// Required.
repeated TreatmentContentFieldTypePb language_specific_content_field_types = 4;
// List of language agnostic content fields. For example, cta_link, image_url.
// Required.
repeated TreatmentContentFieldTypePb language_agnostic_content_field_types = 5;
// List of surfaces where this treatment type can be displayed.
repeated SurfacePb surfaces = 6;
}
message SurfacePb {
// Required.
string name = 1;
}
message TreatmentContentFieldTypePb {
// Name of the content field.
// Required.
string field_name = 1;
// Allowed length of the content field.
// Required.
int32 value_length_limit = 2;
// Data type of the content field.
// Required.
ContentFieldDataType data_type = 3;
}
enum ContentFieldDataType {
CONTENT_FIELD_DATA_TYPE_UNSPECIFIED = 0;
STRING = 1;
}
enum DeliveryType {
DELIVERY_TYPE_UNSPECIFIED = 0;
EMAIL = 1;
IN_APP = 2;
NOTIFICATION = 3;
}
EligibilityRule
message EligibilityRulePb {
// Required.
int64 data_field_id = 1;
// Required.
Condition condition = 2;
// Required.
string rhs_value = 3;
}
enum Condition {
UNSPECIFIED_CONDITION = 0;
LESS_THAN = 1;
LESS_THAN_OR_EQUALS = 2;
GREATER_THAN = 3;
GREATER_THAN_OR_EQUALS = 4;
EQUALS = 5;
NOT_EQUALS = 6;
}
UpdateTreatment API - Sample cURL Request
curl --location --request POST 'https://apis.auxia.io/v1/UpdateTreatment' \
--header 'Content-Type: application/json' \
--header 'x-api-key: TEST_API_KEY' \
--data-raw '{
"project_id": "PROJECT_ID",
"treatment_id": "TREATMENT_ID",
"last_modified_by": "USER_EMAIL",
"name": "Coupon treatment",
"description": "Coupons for Christmas",
"tags": [
{
"name": "christmas_coupons"
}
],
"content": {
"content_by_language": [
{
"language_code": {
"language_code": "en"
},
"content_fields": [
{
"field_name": "title",
"string_value": "50% off"
}
]
}
],
"language_agnostic_content_fields": [
{
"field_name": "cta_link",
"string_value": "http://cta_link"
}
]
},
"target_action": {
"event_id": 123
},
"eligibility_rules": {
"rules": [
{
"data_field_id": 1,
"condition": "GREATER_THAN",
"rhs_value": "18"
},
{
"data_field_id": 2,
"condition": "EQUALS",
"rhs_value": "US"
}
]
},
"mutual_exclusion_group": "MUTUAL_EXCLUSION_GROUP",
"removed_surfaces": {
"surfaces": [
{
"name": "SURFACE"
}
]
}
}'
InsertTreatment API - Sample cURL Request
curl --location --request POST 'https://apis.auxia.io/v1/InsertTreatment' \
--header 'Content-Type: application/json' \
--header 'x-api-key: TEST_API_KEY' \
--data-raw '{
"project_id": "PROJECT_ID",
"name": "CCB treatment",
"description": "Treatment to promote books category",
"treatment_type_name": "IN_APP_CONTENT",
"last_modified_by": "USER_EMAIL",
"start_timestamp": "2017-01-15T01:30:15.010Z",
"end_timestamp": "2027-01-15T01:30:15.010Z",
"content": {
"content_by_language": [
{
"language_code": {
"language_code": "en"
},
"content_fields": [
{
"field_name": "title",
"string_value": "50% off"
}
]
}
],
"language_agnostic_content_fields": []
},
"tags": [
{
"name": "christmas_coupons"
}
],
"external_treatment_id": "EXTERNAL_TREATMENT_ID",
"should_publish": true,
"target_action": {
"event_id": 123
},
"eligibility_rules": {
"rules": [
{
"data_field_id": 1,
"condition": "GREATER_THAN",
"rhs_value": "18"
},
{
"data_field_id": 2,
"condition": "EQUALS",
"rhs_value": "US"
}
]
},
"mutual_exclusion_group": "MUTUAL_EXCLUSION_GROUP",
"removed_surfaces": {
"surfaces": [
{
"name": "SURFACE"
}
]
}
}'
Last updated