Campaigns

Campaigns are split up into templates and instances. The templates define information that is consistent for all users, such as the title, description, images and terms of a campaign. The instance contains the progress of a single user participating in a campaign.

Template

In the API responses the template is typically referred to as the "stack". This entity contains information about a campaign that will be the same for all users.

Schedule

The schedule a campaign dictates wether a campaign will be visible and how users can interact with it. This property is configured on the template. There are three properties on the schedule: visible, earn and burn. The visible period determines when the campaign will be visible to the users. The earn period determines when triggers can be triggered on the users instance as well as wether or not the input methods will be shown. The burn property is not used at the moment.

Blocks

The progress of a user in a campaign is stored inside Blocks. A template can contain one or more Blocks and each Block can appear any number of times on an instance. Each block has a value that indicates the sum of value that is required for it to be considered "full". The value of a block can be set to 0 to indicate that it can be earned indefinitely. Value is earned by Triggers that can be configured on a block. When a trigger is fired it creates a transaction with a certain value that is then stored on the block.

The sum of all transactions can be read from the transaction summary on a block. Below is an example of an instance with a single block. The current balance of the block can be read from remaining_value property on the transaction summary.

{
    "stack_instance_id": "erprc5yg2sof8y20qq7t2yoyc",
    "account_id": "zf8rkqgsjj52glmzo9or1g9dz",
    "stack_id": "zr5mf1xtpsn9orngkxc7ypdyh",
    "builder": "choice",
    "block_definitions": [
        "ssoqrtvs0nwwmfyu0hlo0nett"
    ],
    "blocks": {
        "ssoqrtvs0nwwmfyu0hlo0nett": {
            "DEFAULT_VALUE": 100,
            "block_id": "ssoqrtvs0nwwmfyu0hlo0nett",
            "name": "NeoCoins",
            "instruction": "",
            "label": "",
            "trigger_more_than_once": false,
            "value": 0,
            "images": {},
            "transactions": [],
            "transaction_summary": [{
                "stack_instance_id": "erprc5yg2sof8y20qq7t2yoyc",
                "block_id": "ssoqrtvs0nwwmfyu0hlo0nett",
                "transaction_value": 1100,
                "consumption_value": 0,
                "remaining_value": 1100,
                "last_transaction": {
                    "transaction_id": "dlskj0w5s139da6q2g3bm9sr6",
                    "stack_instance_id": "erprc5yg2sof8y20qq7t2yoyc",
                    "account_id": "zf8rkqgsjj52glmzo9or1g9dz",
                    "state": "new",
                    "reason": "",
                    "value": 100,
                    "consumed": 0,
                    "consumptions": [],
                    "meta": {
                        "trigger_name": "referrer-trigger"
                    },
                    "expires": "",
                    "can_expire": false,
                    "created": "2023-03-13T05:22:05+00:00",
                    "updated": "2023-03-13T05:22:05+00:00"
                }
            }],
            "transaction_summary_all": [{
                "stack_instance_id": "i870qh94ccpctpo8v16m5vot9",
                "block_id": "t2g7atgjkudknu5fxy95qtwj1",
                "transaction_value": 1100,
                "consumption_value": 0,
                "remaining_value": 1100
            }],
            "triggers": [],
            "input_methods": [],
            "can_be_full": true,
            "is_full": false,
            "is_full_percentage": 0,
            "value_display": null
        }
    },
    "block_values": [1100],
    "block_images": [],
    "blocks_total": 1,
    "percent_complete": 0,
    "active": true,
    "state": "active",
    "instance_state": "active",
    "is_full": false,
    "is_deletable": false,
    "has_expired": false,
    "expires": "",
    "created": "2022-12-13T02:25:09+00:00"
}

Instance states

Each instance has two state properties. There is a state attached to the instance itself and each user that is linked to the instance also gets their own state. The state determines in what ways a user can interact with an instance.

The following states exist:

Name	Active	Triggerable	Claimable	Deletable	Expired	Hidden
active	✔	✔	✘	✘	✘	✘
claimable	✔	✘	✔	✘	✘	✘
claimed	✘	✘	✘	✔	✘	✘
inactive	✘	✘	✘	✘	✘	✘
expired	✘	✘	✘	✔	✔	✘
deleted	✘	✘	✘	✘	✘	✔

The 6 boolean fields on a state have the following meaning:

Property	Description	Which state is checked when evaluating this property
Active	Used to split instances into an "active" and "unactive" list in the stack summary endpoints	User state
Triggerable	Configured tiggers are allowed to be executed	Both*
Claimable	A claim button will be shown on the campaign detail page instead of the input methods	User state
Deletable	A delete button will be shown on the campaign detail page instead of the input methods	User state
Expired	Not used at the moment	Instance state
Hidden	The instance will no longer be shown to the user. It will still be visible in the backoffice	Either**

_{*Both: Both the instance and user state need to have this property}
_{**Either: Either the instance or the user state needs to have this property}

The following fields on the instance reflect information about the state of the instance:

Field	Description
`active`	Is `true` when the instance state has the Active property
`state`	Name of the user's state for this instance
`instance_state`	Name of the instance's state
`is_deletable`	Is `true` when the user state has the Deletable property
`has_expired`	Is `true` when the instance state has the Expired property

When configuring a campaign the "Set state" action can be used to change the state of an instance. This will only change the state for the user linked to the instance. The instance state is currently only set when the user manually deletes an instance.

Stack summaries

A Stack summary contains the campaign template(stack) and instance in a single object. Endpoints returning stack summaries are split up into an "active" and "inactive" list. Wether an instance is put into the active or inactive list depends on the user's state on the instance. If that state is treated as active it will be put in the active list, otherwise it will be put in the inactive list.

General campaign information

To fetch all templates you can make a request to /api/2/stacks.

GET /api/2/stacks HTTP/2
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........

{
  "status": 200,
  "message": "",
  "result": [
    {
      "stack_id": "fgpigr30f5wvdna109nlhinwa",
      "title": "Campaign title",
      "instruction": "An instruction",
      "description": "<p>A description</p>",
      "terms": null,
      "thumbnail": null,
      "type": "challenge",
      "type_meta": {
        "delete_url": "/api/1/stack-instances/delete/{stack_instance_id}",
        "claim_url": "/api/1/stack-instances/claim/{stack_instance_id}"
      },
      "ongoing": true,
      "start": "",
      "end": "",
      "redeem_start": "",
      "redeem_end": "",
      "online": "",
      "offline": "",
      "blocks": [
        {
          "DEFAULT_VALUE": 100,
          "block_id": "bdi6jswfepoqk4jcltg9xib8e",
          "name": "Test block",
          "instruction": "",
          "label": "",
          "trigger_more_than_once": false,
          "value": 100,
          "images": [],
          "default_transaction_expiration": null,
          "transactions": [],
          "transaction_summary": [],
          "transaction_summary_all": [],
          "triggers": [],
          "input_methods": [],
          "can_be_full": true,
          "value_display": null
        }
      ],
      "actions": [],
      "images": [],
      "cta_value": null,
      "cta_url": null,
      "cta_mobile_value": "",
      "cta_mobile_il": "",
      "cta_mobile_ilt": "",
      "preferredDeeplink": "",
      "active": 1,
      "schedule": {
        "id": "yvsq3ze89vosm9xr7zv5hm6vs",
        "name": "stack-schedule",
        "title": "Campaign schedule",
        "data": {
          "stack_id": "fgpigr30f5wvdna109nlhinwa",
          "visible": {
            "id": "rjckinikks97jbi22c75hb5iw",
            "name": "visible",
            "description": "",
            "dateRange": {
              "startDate": null,
              "endDate": null
            }
          },
          "earn": {
            "id": "vkhmqtury6ms63tnzrwd7naj8",
            "name": "earn",
            "description": "",
            "dateRange": {
              "startDate": null,
              "endDate": null
            }
          },
          "burn": {
            "id": "do8pdnnry59vrpebrnwmjp6lk",
            "name": "burn",
            "description": "",
            "dateRange": {
              "startDate": null,
              "endDate": null
            }
          }
        }
      },
      "status": "incomplete",
      "created": "2023-04-18T08:09:28+00:00",
      "redeem": ""
    }
  ]
}

User specific information

To fetch the instances of a user for a specific campaign you can make a request to /api/1/backoffice/stack-instances/{stack_id}/{user_id}.

GET /api/1/backoffice/stack-instances/n90e7f5f1010fa277cf39786b/fl85jmyfjos2k9sh09408eoxx HTTP/2
Host: gateway.acme.neo.day
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9........

{
  "status": 200,
  "message": "",
  "result": [
    {
      "stack_instance_id": "j3b89tww8q6f3qwqol8fx6yyb",
      "account_id": "fl85jmyfjos2k9sh09408eoxx",
      "stack_id": "n90e7f5f1010fa277cf39786b",
      "builder": "choice",
      "block_definitions": [
        "v8ab217c66c7a238c62703d82",
        "v8ab217c66c7a238c62703d82",
        "v8ab217c66c7a238c62703d82"
      ],
      "blocks": {
        "v8ab217c66c7a238c62703d82": {
          "DEFAULT_VALUE": 100,
          "block_id": "v8ab217c66c7a238c62703d82",
          "name": "Block A",
          "instruction": "",
          "label": "",
          "trigger_more_than_once": false,
          "value": 100,
          "images": [],
          "transactions": [],
          "transaction_summary": [],
          "transaction_summary_all": [],
          "triggers": [],
          "input_methods": [],
          "can_be_full": true,
          "is_full": false,
          "is_full_percentage": 0,
          "value_display": null
        }
      },
      "block_values": [0,0,0],
      "block_images": [],
      "blocks_total": 3,
      "percent_complete": 0,
      "active": true,
      "state": "active",
      "instance_state": "active",
      "is_full": false,
      "is_deletable": false,
      "has_expired": false,
      "expires": "",
      "created": "2023-04-18T13:57:45+00:00"
    }
  ]
}