|
| 1 | +# Ascend Java SDK |
| 2 | + |
| 3 | +#### Vocabulary |
| 4 | + |
| 5 | + **Participant:** The end user of the application, the individual who's actions are being recorded in the experiment. |
| 6 | + **Allocation:** The set of configurations that have been given to the participant, the values that are being |
| 7 | + experimented against. |
| 8 | + |
| 9 | +### Client Initialization |
| 10 | + |
| 11 | +1. Build an AscendConfig instance. |
| 12 | + ```java |
| 13 | + AscendConfig config = AscendConfig.builder(<environment_id>).build(); |
| 14 | + ``` |
| 15 | + |
| 16 | +2. Initialize the AscendClient. |
| 17 | + ```java |
| 18 | + AscendClient client = AscendClientFactory.init(config); |
| 19 | + ``` |
| 20 | + |
| 21 | +### Confirm the Allocation |
| 22 | + |
| 23 | +1. Once the client has been initialized, confirm the participant into the experiment. |
| 24 | + ```java |
| 25 | + client.confirm(); |
| 26 | + ``` |
| 27 | + *Note: After the client has initialized, it is important to confirm the participant into the experiment. This action |
| 28 | + records the participant's allocation and sends the info back to Ascend.* |
| 29 | +
|
| 30 | +### Value Retrieval |
| 31 | +
|
| 32 | +1. Retrieve values from Ascend. |
| 33 | + ```java |
| 34 | + T value = client.get(<key_for_value>, <default_value>); |
| 35 | + ``` |
| 36 | + |
| 37 | + *Note: The return value's type is decided by the provided default value's type. If there is an issue retrieving the |
| 38 | + requested value, the default value will be returned in its place. This method is blocking, it will wait until the |
| 39 | + allocation has been received.* |
| 40 | + |
| 41 | +### Value Subscription |
| 42 | +
|
| 43 | +You may want to use a value from your allocation without blocking the execution of your application. If this is true, you can |
| 44 | +subscribe to a value and apply any actions as a result of it asynchronously. |
| 45 | +
|
| 46 | +1. Subscribe to a value from Ascend. |
| 47 | + ```java |
| 48 | + client.subscribe(<key_for_value>, <default_value>, value -> { |
| 49 | + Your code... |
| 50 | + }); |
| 51 | + ``` |
| 52 | + |
| 53 | + *Note: The return value's type is decided by the provided default value's type. If there is an issue retrieving the |
| 54 | + requested value, the default value will be returned in its place. If you have a previous allocation stored the |
| 55 | + value will be retrieved and then your code will be executed. When the new allocation is retrieved if the value |
| 56 | + differs from the previously stored allocation then your code will be ran again with the new value. If your code |
| 57 | + results in an Exception it will be thrown.* |
| 58 | + |
| 59 | +### Custom Events (optional) |
| 60 | +
|
| 61 | +Sometimes you may want to record certain events that occurred during the participant's session. An example of an event |
| 62 | +thats important to record is a "conversion" event. If you implemented the SDK in a shopping app, you could send the |
| 63 | +"conversion" event when the participant presses the checkout button. |
| 64 | + |
| 65 | +1. Emit a custom event. |
| 66 | + ```java |
| 67 | + client.emitEvent(<event_type>); |
| 68 | + ``` |
| 69 | + |
| 70 | + AND / OR |
| 71 | + |
| 72 | +2. Emit a custom event with an associated score. |
| 73 | + ```java |
| 74 | + client.emitEvent(<event_type>, <score>); |
| 75 | + ``` |
| 76 | + |
| 77 | +### Contaminate the Allocation (optional) |
| 78 | + |
| 79 | +Sometimes it may be necessary to contaminate the participant's allocation. Meaning, that you may not want that participant's session to be recorded into the experiment. |
| 80 | + |
| 81 | +1. Contaminate the participant's allocation. |
| 82 | + ```java |
| 83 | + client.contaminate(); |
| 84 | + ``` |
| 85 | + |
| 86 | +### Custom Allocation Store (optional) |
| 87 | +
|
| 88 | +Once a participant has been allocated into an experiment you may want to retain the allocations they received. To do this, create a custom allocation store by implementing the AscendAllocationStore interface. You can supply the |
| 89 | +custom allocation store to the client when you build the AscendConfig. |
| 90 | +
|
| 91 | +1. Supply the allocation store to the client. |
| 92 | + ```java |
| 93 | + AscendConfig config = AscendConfig.Builder(<environment_id>) |
| 94 | + .setAscendAllocationStore(<custom_store>) |
| 95 | + .build(); |
| 96 | + AscendClient client = AscendClient.init(config); |
| 97 | + ``` |
| 98 | + |
| 99 | +### Optional Configurations |
| 100 | +
|
| 101 | +There are several optional configurations available through the AscendConfig builder, check out the AscendConfig |
| 102 | +documentation to see what options are available. |
| 103 | +
|
| 104 | +### About Evolv and the Ascend Product |
| 105 | +
|
| 106 | +Evolv Delivers Autonomous Optimization Across Web & Mobile. |
| 107 | +
|
| 108 | +You can find out more by visiting: https://www.evolv.ai/ |
0 commit comments