Ressources & Operations

  • A project is used by clients to conduct A/B tests and/or to deliver personalized content.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    idintRRInternal project ID
    typestringRWRWxType of project:
    • VISUAL: Visual A/B-test
    • SPLIT: Split-test
    mainurlstring, 1024RWRWxA URL representing the main original URL of a project. It is used to create a preview page and internal documentation.

    Syntactically invaid URLs (protocol missing etc.) will raise an error.
    runpatternstring, 1024RWRWxPattern (typically for a URL) which determines whether or not the project runs on a given URL or not. Oftentimes it is identical to mainurl.
    An asterisk (*) can be used as a wildcard in the URL.
    createddatedatetimeRRDate and time when project has been created
    startdatedatetimeRWRWProject does not collect before this datetime. The format is 'YYYY-MM-DD hh:mm:ss', e.g.
    '2015-04-22 22:10:12'.
    enddatedatetimeRWRWProject does not collect after this datetime. The format is 'YYYY-MM-DD hh:mm:ss'
    restartdatedatetimeRRDate when project has been restarted the last time
    remainingdaysintRRNumber of days needed to make the project significant. In case this number cannot be computed yet, this fields contains -1.
    nameintstring, 128RWRWxName of the project, does not need to be unique.
    statusstringRRShows wether project is running or not:
    • PAUSED
    • RUNNING
    visitorsintRRNumber of visitors that have participated in this project.
    conversionsintRRNumber of conversions in this project.
    conversionratefloatRRConversions divided by Visitors. If an A/B test is statistically significant, the conversion rate of the winning decision is returned here.
    resultstringRRThe result of the project, meaningful for A/B-testing only.
    • NA: Not applicable. The project is no A/B-test and has thus no result.
    • NONE: The A/B test is not significant yet.
    • LOST: The control decision has the highest conversion rate.
    • WON: At least one decision has a higher conversion rate than the control.
    originalidintRRID of the original decision.
    winneridintRRIn case result=WON this field contains the ID of the winning decision (and -1 if result != WON).
    winnernamestringRRIn case result=WON this field contains the name of the winning decision (and 'NA' if result != WON)
    upliftfloatRRIn case result=WON this field contains the improvement of conversion rate of the winning decision relative to the original decision (and -1 if result != WON)
    autopilotstringRRTells wether autopilot is running or not.
    • NA: Not applicable because the project is no A/B test and has thus no significance.
    • RUNNING: significant decisions are cut off from traffic and the best decision is delivered on end of test
    • PAUSED: all decisions are delivered equally distributed
    allocationint RW RW Value between 0 and 100. Determines the percentage of visitors to be allocated to this test. Default is 100.
    ipblacklistingbooleanRW RW (true|false) Determines whether or not an IP blacklisting for the account is applied for this project (default is true)
    personalization modestring RW RW Determines how personalization is managed in this project:
    • NONE: No personalization for this project.
    • COMPLETE: The project as a while is personalized, this means we have a personalized A/B test.
    • SINGLE: Each decision can be assigned it's own personalization rule. The original is not delivered anymore.
    The default is NONE. If this field is set to SINGLE or COMPLETE and personalization is not an available feature (see the account resource), then an error is raised.
    ruleidintRW RW In case personalization mode is set to COMPLETE, this value refers to the rule resource which determines whether the project is delivered to visitors or not.
    If the field is empty AND personalization mode = COMPLETE, then an error is returned.
    • In the following description, all resource URIs are noted without the leading API path and the segment identifying the account. So when the following URI is mentioned POST /project/ We refer in fact to a URI similar to this: POST https://www.blacktri.com/api/v1/account/4711/project/
      • Create a new project and return the project's URI. A project object is passed in the request body.
        Update an existing project. A project object is passed in the request body.
        Get data for an existing project.
        Delete all report data for a project and start over. No object is passed in the request body, and no data are provided in the response.
        Pause a project. No object is passed in the request body, and no data are provided in the response.
        Start a project. No object is passed in the request body, and no data are provided in the response.
        Delete an existing project.
        Retrieves a list of all projects of the given account in the URI. The response will contain an ordered list of project objects. The list can be searched/filtered with the following query string qualifiers that refer to values of the resource attributes (see above).
        Name
        type
        status
        The result list can be sorted by providing the qualifier sort with one of the following attributes. A dash can be added to the attribute to indicate descending order.
        Name
        createddate
        name
        The fields contained in the result set can be determined or limited by providing a parameter fields with a comma separated list of field names. The following fields are contained in the resultset as default:
        Name
        id
        name
        mainurl
        visitors
        conversions
        conversionrate
        result
        uplift
        remainingdays
        Example: GET /account/4711/projects?sort=-createddate&status=RUNNING&fields=id,name,conversionrate
        Stop the project autopilot. No object is passed in the request body, and no data are provided in the response.
        Start the project autopilot. No object is passed in the request body, and no data are provided in the response.
    A decision is one out of a set of contents which can be delivered in a project. There is always one decision called the "original" or "control" decision which is the entity that shall be optimized, for example a web page. Additional variant decisions can be defined which are delivered alternatively. In an A/B test they are delivered together with the control in a random manner, in case of personalization they are delivered depending on whether personalization rules are matching or not.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    idintRRInternal decision ID
    namestring, 128RWRWxName of the decision, does not need to be unique.
    urlstring, 1024RWRWOnly relevant for Split-Test variants: contains the URL that shall be called instead of the control.
    previewurlstring, 102RRA URL which opens a preview of the decision.
    typestringRRThe type of decision:
    • CONTROL
    • VARIANT
    The type cannot be set. When creating a project, the control decision is created automatically. All additional decisions are of type VARIANT.
    ruleidintRWRWFor projects where
    • personalization mode is set to SINGLE
    • AND the type of this decision is VARIANT
    this field refers to to the rule resource which determines whether the decision is delivered to visitors or not. If the field is empty, the decision is not personalized.
    resultstringRRThe result/status that this variant has in an A/B test:
    • NA: Not applicable since the project is no A/B test
    • NONE: The status is not known since confidence is not significant yet.
    • LOST:
    o If the decision is the control: There is at least one variant decision with a higher conversion rate.
    o If the decision is a variant: The control has a higher conversion rate than this decision.
    • WON:
    o If the decision is the control: There is no variant decision with a higher conversion rate.
    o If the decision is a variant: The control has a lower conversion rate than this decision.
    visitorsintRRNumber of visitors that have participated in the project and been delivered the decision.
    conversionsintRRNumber of visitors that have participated in the project and been delivered the decision and converted subsequently.
    conversion ratefloatRRConversion rate of this decision (conversions / visitors).
    confidencefloatRRA value between 0.5 and 1 representing the probability that the result is not by accident. In case the confidence cannot be calculated it is 0.
    distributionfloatRRA value between 0 and 1 representing the probability this decision will be delivered to a visitor.
    jsinjectiontextRWRWJavascript code to be injected into a webpage to visualize the content of the decision. This is only applicable for projects of type VISUAL.
    cssinjectiontextRWRWCSS code to be injected into a webpage to visualize the content of the decision. This is only applicable for projects of type VISUAL.
    • In the following description, all resource URIs are noted without the leading API path and the segment identifying the decision. So when the following URI is mentioned POST /decision/ We refer in fact to a URI similar to this: POST https://www.blacktri.com/api/v1/account/4711/project/456/decision/
      • Create a new decision and return the decision's URI. A decision object is passed in the request body. Only decisions of type variant can be created like this, the control decision is created implicitly when creating the project.
        Update an existing decision. A decision object is passed in the request body.
        Get data for an existing decision.
        Delete an existing decision. The control decision cannot be deleted.
        Retrieves a list of all decisions of the given project in the URI. The response will contain an ordered list of decision objects. The result list can be sorted by providing the qualifier sort with one of the following attributes. A dash can be added to the attribute to indicate descending order. For all sort operations the control decision will be the first in the list.
        Name
        name
        conversionrate
        The list can be searched/filtered with the following querystring qualifiers that refer to values of the resource attributes (see above).
        Name
        result
    A goal is a criterion to attach a conversion event to a decision. It typically represents a user action or the technical event that indicates a certain action. Goals are assigned to projects. Most of them only apply to online/mobile based projects.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    idintRRInternal goal ID
    typestringRWRWxType of goal, one of the following:
    • ENGAGEMENT: user clicks a link on the landingpage.
    • AFFILIATE: user klicks a link which is from a known affiliate network.
    • TARGETPAGE: user loads a page with a given URL. An asterisk (*) can be used as a wildcard in the URL.
    • LINKURL: user klicks a link with a given URL. An asterisk (*) can be used as a wildcard in the URL.
    • CUSTOMJS: user does something that triggers calling a certain predifined Javascript function.
    paramstring, 512RWRWAn optional parameter, needed for some of above goals:
    • If goal is TARGETPAGE: URL of page that shall be opened.
    • If goal is LINKURL: URL of link that shall be clicked.
    • In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned POST /goal/ We refer in fact to a URI similar to this: POST https://www.blacktri.com/api/v1/account/4711/project/456/goal/
      • Create a new goal and return the goal's URI. A goal object is passed in the request body.
        Update an existing goal. A goal object is passed in the request body.
        Get data for an existing goal.
        Delete an existing goal.
        Retrieves a list of all goals of the given project in the URI. The response will contain an ordered list of goal objects. The list can be searched/filtered with the following querystring qualifiers that refer to values of the resource attributes (see above).
    The condition resource represents a personalization condition which is always part of a rule.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    idintRRInternal condition ID
    negationbooleanRWRWx(true|false) Whether the condition or it's negation must be met:
    true: the condition's result will be negated before it gets returned
    false: the conditions original value gets returned
    typestringRWRWxThe kind of condition that will be evaluated. Which types are available is depending on the tenant and server implementation. Currently one out of the following:
    • REFERRER_CONTAINS: the given substring ist contained in the HTTP referrer.
    • URL_CONTAINS: the given substring is contained in the URL or querystring.
    • SOURCE_IS: the referrer depicts that the visitor's traffic source is as specified.
    • IS_RETURNING: the visitor is a new visitor vs. a returning visitor.
    • SEARCH_IS: the traffic source is paid or organic search with one or more of the given keywords.
    • TARGETPAGE_OPENED: visitor has opened the given page URL one or more times. Asterisk can be used as wildcard in URL.
    • DEVICE_IS: visitor uses the given device.
    • ETRACKER_RTA: Visitor profile as returned from the etracker Real Time API matches the provided argument
    arg1string, 255RWRWAn argument, necessary for most of the rules (e.g. a substring for URL_CONTAINS). The following shows condition types where an argument is necessary, together with the allowed values:
    • REFERRER_CONTAINS
    • string with the following validation: alphanumeric (numbers and letters) and the following characters: &_-
    • URL_CONTAINS
    • string with the following validation: alphanumeric (numbers and letters) and the following characters: &_-
    • SOURCE_IS: one of the following
    • TYPE_IN: no referrer
    • SOCIAL: social media
    • ORGANIC_SEARCH: organic search
    • PAID_SEARCH: paid earch
    • IS_RETURNING: one of the following
    • YES: is a returning visitor
    • NO: is new
    • SEARCH_IS
    • A string with one or more words, separated by blanks. Validation is: alphanumeric (numbers and letters) and blanks.
    • TARGETPAGE_OPENED
    • string with the following validation: alphanumeric (numbers and letters) and the following characters: &_-.*
    • DEVICE_IS: one of the following
    • MOBILE
    • TABLET
    • DESKTOP
    • ETRACKER_RTA: a match with a certain RTA attribute has to be provided as JSON string according to the following description:
    • "attribute": Name of the RTA attribute
    • "comparator": One out of
    • EQUALS
    • NOT_EQUALS
    • TO
    • FROM
    • GREATER_THAN
    • LESS_THAN
    • "value": Return value of the API to be matched
    • In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned POST /condition/ We refer in fact to a URI similar to this: POST https://www.blacktri.com/api/v1/account/4711/rule/4567/condition/
      • Create a new condition and return the condition's URI. A condition object is passed in the request body.
        Update an existing condition. A condition object is passed in the request body.
        Get data for an existing condition.
        Delete an existing condition.
        Retrieves a list of all conditions of the given rule in the URI. The response will contain an ordered list of condition objects.
    An account represents the client or user who creates and manages projects to conduct A/B testing or deliver personalized content on his website, app or application. Since account might be purchased by customers, they can be packed with different amounts of quota and different feature sets. A client could access the account (and all other resources) from a website which is operated by an API-Tenant (etracker and etracker partners are treated as API-Tenants themselves), in which case the API-Tenant uses the API to provide all necessary backend functionality on the website. Alternatively and if desired additionally, the client could use the API to do the same which the website would allow.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    IdintRRInternat account ID
    Subidstring, 64RWROptional custom account ID for user system
    publicidstring, 40RWRPublicly used account ID string (e.g. in tracking code). Must be unique among all accounts. If no publicid is provided when the account is created, an ID is assigned automatically and can be read from the resource after creation.
    emailstring, 255RWREmail address. When set it must be unique for all accounts of a tenant.
    passwordstring, 128RW-The account's password.
    apikeystring, 64RW-The account's API secret. After creation of the account it is empty and needs to be set by the API tenant.
    emailvalidatedbooleanRWRIndicates email has been verified by a double opt-in mail.
    custom1string, 64RWRCustom field.
    custom2string, 64RWRCustom field.
    custom3string, 64RWRCustom field.
    FeaturesarrayRW-An array indicating which features of etracker Testing & Targeting the account has permissions for. This can be used to create "packages" or "plans" with certain sets of features.
    See the table below for possible values.
    firstnamestring, 128RWRWFirst name of account user.
    lastnamestring, 128RWRWLast name of account user.
    StatusintRWRxStatus of this account:
    • EVALUATION: Accounts in evaluation phase can be assigned a quota, and this quota will not automatically be renewed each month.
    • FULL: An account with full access and monthly renewed quota.
    • HIBERNATED: The client can still log in to change some profile data and manage projects, but all projects are stopped.
    • CANCELLED: The account has been cancelled, users can not log in or use the account in any other way.
    Plan0intRWRAn ID indicating the user plan. There is no logic in etracker that makes use of it, it is more an identifier for the API-Tenant, who can set the quota or give access to
    createddatedatetimeRRDate and time when the account has been created.
    quotaintRWRxAvailable quota of unique visitors per month.
    usedquotaintRRAmount of used quota in the current 30-day-period which starts each month on the day indicated in quota_reset_dayinmonth
    freequotaintRWRDefault 0Amount of monthly quota which will not be billed.
    quotareset dayinmonthintRRDay in month (1-28) to reset the used quota to 0. Days 29 to 31 are not used in order to be able to use the same day in each month (even february)
    ipblackliststring, 1024RWRWA semicolon separated list of IP address substrings which shall be excluded for visitors.
    trackingcodestringRRThe etracker Tracking Code to be included in the client website.
      • An API-Tenant can use the account resource to provide registration and login functionality for his clients. He can read and write the necessary data via the API, but still has to implement functionality of web based registration, login, password reminder etc. by himself.
      • The API-Client can change only small parts of the account resource by himself, since most attributes are either in control of the API-Tenant (like userplan) or should be changed only by a UI provided from the API-tenant (like the password) or are under control of etracker (like the used quota).
      • If an API-Tenant needs more fields to fully manage a relationship to a client, he can make use of the 3 custom fields, or needs to store additional data in a local database where rows have a 1:1 relationship to the account resource (meaning: they should use the account id as foreign key).
      The field publicid is used as the account identifier in the etracker Testing Tag which has to be inserted in the client's web pages for content injection. It thus needs to be unique among all accounts inside etracker Testing & Targeting. It can be left empty when creating an account, a unique value will then be created by the API. Alternatively, the tenant can provide a value and the API will raise an error if it is not unique.
      • When the tenant creates an account, she has to determine how a client authenticates herself and interacts with the system: If the tenant provides a web application where clients can log in with email and password, the tenant should provide these fields when creating an account. To validate a client, the tenant would retrieve accounts with GET /accounts/ and provide email and password as filters (see below). This means the tenant would provide business logic to authenticate clients by herself. We recommend not storing the password in clear text, but creating an md5 hash first before sending it to the API.
      • The tenant can additionally order alternatively provide an API key and API secret to the client. The client could access the API herself using these credentials. etracker creates an API key for every new account, and if the tenant provides an API secret the client could use these data to get API access. As long as the API secret is not set, no API access is possible.
      The features array (see above) can have attributes as specified in the following table. In case an attribute is not contained, the default is used (thus the features array could be completely empty or not being passed when creating accounts).
      NameDescription
      visualtest(true|false) Projects of type "Visual A/B Test" can be created. The default is true.
      splittest(true|false) Projects of type "Split Test" can be created. The default is true.
      personalization(true|false) Personalization rules can be managed and assigned to projects. The default is true.
      startenddate(true|false) Start and end date can be set for a project. The default is true.
      numdecisions(1..n) The maximum number of variant decisions that can be created for a project. The default is unlimited.
      numactiveprojects(1..n) The maximum number of running projects at the same time. The default is unlimited.
      In the following description, all resource URIs are noted without the leading API path and the segment identifying the account. So when the following URI is mentioned. Please not that deletion of accounts is not allowed. To deactivate an account, the api tenant can set the status to "CANCELLED". POST /account/ We refer in fact to a URI similar to this: POST https://www.blacktri.com/api/v1/account/
      • Create a new account and return the account's URI. Only allowed for API-Tenants. An account object is passed in the request body.
        Update an existing account. An account object is passed in the request body.
        • Allowed for both API-Tenants and API-Clients.
        • Write permissions apply as depicted in the table above.
        Get data for an existing account.
        • Write permissions apply as depicted in the table above.
        Only allowed for API-Tenants. Retrieves a list of all accounts they created (the result provides the URI for each account). The response will contain an ordered list of account objects. The list can be searched/filtered with the following query string qualifiers that refer to values of the resource attributes (see above).
        Name
        subid
        publicid
        custom1
        custom2
        custom3
        apikey
        apisecret
        email
        emailvalidated
        status
        Example: /accounts/?email=test@google.de&password=thisissecret Retrieve an account for a given email and password to implement a login functionality. /accounts/?status=FULL Retrieve a list of all active (payed) accounts. The result list can be sorted by providing the qualifier sort with one of the following attributes. A dash can be added to the attribute to indicate descending order.
        Name
        publicid
        custom1
        custom2
        custom3
        apikey
        email
        createdate
        Example: /accounts/?sort=email Retrieves all accounts sorted ascending by email. /accounts/?sort=-createddate Retrieves all accounts sorted descending by creation date. All qualifiers can be combined: /accounts/?sort=-createddate&status=FULL
    The rule resource represents a personalization rule, consisting of one or more condition resources.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    idintRRInternal rule ID
    namestring, 128RWRWxDisplay name of the rule
    operationstringRWRWxThe boolean operator to combine all related conditions. One out of:
    • AND
    • OR
    conditionslistRRA list of related conditions resource objects.
    • In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned POST /rule/ We refer in fact to a URI similar to this: POST https://www.blacktri.com/api/v1/account/4711/rule/
      • Create a new goal and return the rule's URI. A rule object is passed in the request body.
        Update an existing rule. A rule object is passed in the request body.
        Get data for an existing rule.
        Delete an existing rule.
        Retrieves a list of all rules of the given account in the URI. The response will contain an ordered list of rule objects.
    The trend resource represents an array of data sets, each containing impressions and conversions of a decision resource in a given period of time. The trend resource can thus be used to populate charts or create custom reports.
    FieldTypePermissions
    API Tenant
    Permission
    API Client
    Mandatory
    On Create
    Message
    timestampsarrayRRAn array of datetime-objects, each representing the sample date and time of one data point. Currently each timestamp represents one day.
    datasetsarrayRRAn array of dataset objects. Each represents one decision in a project. The first dataset is by convention the original ("control").
    Each dataset contains the three arrays below (impressions, conversions, aggregatedcr).

    .....namestringRRThe name of the decision.
    .....impressionsarrayRRAn array of int. Each value represents the number of impressions for the decision on the corresponding timestamp.
    .....conversionsarrayRRAn array of int. Each value represents the number of conversions for the decision on the corresponding timestamp.
    .....aggregatedcrarrayRRAn array of float. Each value represents the conversion rate for the decision on the corresponding timestamp, aggregated over all impressions and conversions since starting or restarting the project.
    • In the following description, all resource URIs are noted without the leading API path and the segment identifying the goal. So when the following URI is mentioned GET /trend/ We refer in fact to a URI similar to this: GET https://www.blacktri.com/api/v1/account/4711/project/2435/trend/ Retrieves a trend object for a certain time period. The result can be parametrized with the following query string qualifiers.
      NameTypeDescription
      enddatetimeSpecifies the latest required timestamp in the result.
      entriesintNumber of datapoints / timestamps in the result (currently translated to the number of days in the result).
      The default is 30.
      goalidintA goal for which conversions shall be calculated.

Need help?
Our friendly, knowledgeable support engineers are here for you.