dopaminekit 0.2.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +184 -11
- data/lib/dopaminekit/version.rb +1 -1
- data/lib/dopaminekit.rb +55 -26
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 42c98ae7d9991c9bd6f72583fbd7c661b87ae8f1
|
|
4
|
+
data.tar.gz: c729101c6712f0956ddb6bd3dc2d835735ba891a
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 3ac5ca4263b309d47340a3f00b827db50a2c6cbabf51c04077f738ba9cd3bd29a09a5f6ed140991dae43ae8c0ecf189006f6d3d2dd1a96c24aae28d876c51457
|
|
7
|
+
data.tar.gz: 689411ff4c733dc056da6c522917b6e8bf83bf747169bd9d008c3da39d30d4ed76604692221e98efe9c2396f6762114335c1bbb8bee8883c503efce4b2806504
|
data/README.md
CHANGED
|
@@ -1,28 +1,201 @@
|
|
|
1
|
-
# DopamineKit
|
|
1
|
+
# What is DopamineKit?
|
|
2
|
+
Boost retention and user engagement in your python app
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
DopamineKit provides wrappers for accessing the DopamineAPI and expressive UI reinforcements for your app.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Get your free API key at [http://dashboard.usedopamine.com/](http://dashboard.usedopamine.com/)
|
|
7
|
+
|
|
8
|
+
Learn more at [http://usedopamine.com](http://usedopamine.com)
|
|
6
9
|
|
|
7
10
|
## Installation
|
|
8
11
|
|
|
9
|
-
Add this line to your application's Gemfile:
|
|
12
|
+
1. Add this line to your application's Gemfile:
|
|
10
13
|
|
|
11
|
-
```ruby
|
|
12
|
-
gem 'dopaminekit'
|
|
13
|
-
```
|
|
14
|
+
```ruby
|
|
15
|
+
gem 'dopaminekit'
|
|
16
|
+
```
|
|
14
17
|
|
|
15
|
-
And then execute:
|
|
18
|
+
2. And then in terminal execute:
|
|
16
19
|
|
|
20
|
+
```
|
|
17
21
|
$ bundle
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Or
|
|
18
25
|
|
|
19
|
-
|
|
26
|
+
1. Install it into the ruby environment yourself as:
|
|
20
27
|
|
|
28
|
+
```
|
|
21
29
|
$ gem install dopaminekit
|
|
30
|
+
```
|
|
22
31
|
|
|
23
32
|
## Usage
|
|
24
33
|
|
|
25
|
-
|
|
34
|
+
1. First, make sure you have received your API key and other credentials, which are automatically generated from the [Dopamine Developer Dashboard](http://dashboard.usedopamine.com).
|
|
35
|
+
|
|
36
|
+
2. Import DopamineKit
|
|
37
|
+
|
|
38
|
+
```ruby
|
|
39
|
+
require 'dopaminekit'
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
- __Note:__ You may need to use `require 'rubygems'` as well
|
|
43
|
+
|
|
44
|
+
3. Create a DopamineKit object with your credentials passed in as Strings
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
## Credentials for your Dopamine account
|
|
48
|
+
appID = "generated from dashboard.usedopamine.com"
|
|
49
|
+
developmentSecret = "generated from dashboard.usedopamine.com"
|
|
50
|
+
productionSecret = "generated from dashboard.usedopamine.com"
|
|
51
|
+
versionID = "testing"
|
|
52
|
+
inProduction = false
|
|
53
|
+
debugMode = true
|
|
54
|
+
|
|
55
|
+
## Create a DopamineKit object
|
|
56
|
+
dopaminekit = DopamineKit.new(appID, developmentSecret, productionSecret, versionID, inProduction, debugMode)
|
|
57
|
+
|
|
58
|
+
...
|
|
59
|
+
## Reinforcement Call
|
|
60
|
+
responseFunction = dopaminekit.reinforce("action1", "ken@hotmail.com")
|
|
61
|
+
|
|
62
|
+
...
|
|
63
|
+
## Tracking Call
|
|
64
|
+
dopaminekit.track("trackedAction", "ken@hotmail.com")
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
4. Start using Dopamine! The main features of DopamineAPI are the `reinforce()` and `track()` functions. These should be added into the response functions of any _action_ to be reinforced or tracked.
|
|
68
|
+
|
|
69
|
+
There is also the `addPersistentMetaData(key, value)` to add metadata that is persistent throughout calls, and is cleared with the `clearPersistentMetaData()`.
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
### Actions that represent Habits
|
|
73
|
+
|
|
74
|
+
Reinforce your apps _essential_ actions; what users come to your app to do. Three actions is definitely enough, and one is often best.
|
|
75
|
+
|
|
76
|
+
## Super Users
|
|
77
|
+
|
|
78
|
+
There are additional parameters for the `track()` and `reinforce()` functions that are used to gather rich information from your app and better create a user story of better engagement.
|
|
79
|
+
|
|
80
|
+
========
|
|
81
|
+
|
|
82
|
+
####Object Initialization
|
|
83
|
+
|
|
84
|
+
The object initialization takes in the API credentials (appID, development and production secrets, and the versionID). There are also the options inProduction, which selects between the development and billed production mode, and debugmode, which prints out the sent and received API calls when set to True.
|
|
85
|
+
|
|
86
|
+
######General syntax
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
dopaminekit = DopamineKit.new(appID, developmentSecret, productionSecret, versionID, inProduction, debugMode=false)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
######Parameters:
|
|
93
|
+
- `appID: String` - Uniquely identifies your app, get this from your [developer dashboard](http://dev.usedopamine.com).
|
|
94
|
+
|
|
95
|
+
- `developmentSecret : String` - secret key for development
|
|
96
|
+
|
|
97
|
+
- `productionSecret : String` - secret key for production
|
|
98
|
+
|
|
99
|
+
- `versionID : String` - this is a unique identifier that you choose that marks this implementation as unique in our system. This could be something like 'summer2015Implementation' or 'ClinicalTrial4'. Your `versionID` is what we use to keep track of what users are exposed to what reinforcement and how to best optimize that.
|
|
100
|
+
|
|
101
|
+
- `inProduction : Boolean` - indicates whether app is in production or development mode, when you're happy with how you're integrating Dopamine and ready to launch set this argument to `true`. This will activate optimized reinforcement and start your billing cycle. While set to `false` your app will receive dummy reinforcement, new users will not be registered with our system, and no billing occurs.
|
|
102
|
+
|
|
103
|
+
- `debugMode : Boolean=false` - Enables debug mode, where the sent and received data are printed. Can be updated with `enableDebugMode(Boolean)`.
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
========
|
|
107
|
+
|
|
108
|
+
####Tracking Calls
|
|
109
|
+
|
|
110
|
+
A tracking call should be used to record and communicate to DopamineAPI that a particular action has been performed by the user, each of these calls will be used to improve the reinforcement model used for the particular user. The tracking call itself is asynchronous and non-blocking. Failed tracking calls will not return errors, but will be noted in the log.
|
|
111
|
+
|
|
112
|
+
######General syntax
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
Dopamine.track(actionID, identity, metaData=nil)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
######Parameters:
|
|
119
|
+
- `actionID : String` - A descriptive name for action that the user has performed
|
|
120
|
+
|
|
121
|
+
- `identity : String` - A string used to identify a particular user, such as an email or username or UUID.
|
|
122
|
+
|
|
123
|
+
- `metaData : Hash=nil` - An optional hash containing extra data about the user or environment to generate better results.
|
|
124
|
+
|
|
125
|
+
========
|
|
126
|
+
|
|
127
|
+
####Reinforcement Calls
|
|
128
|
+
|
|
129
|
+
A reinforcement call should be used when the user has performed a particular action that you wish to become a 'habit', the reinforcement call will return the name of the feedback function that should be called to inform, delight or congratulate the user. The names of the reinforcement functions, the feedback functions and their respective pairings may be found and configured on the developer dashboard.
|
|
130
|
+
|
|
131
|
+
######General syntax
|
|
132
|
+
|
|
133
|
+
```
|
|
134
|
+
Dopamine.(actionID, identity, metaData=nil)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
######Parameters:
|
|
138
|
+
|
|
139
|
+
- `actionID : String` - A descriptive name for action that the user has performed
|
|
140
|
+
|
|
141
|
+
- `identity : String` - A string used to identify a particular user, such as an email or username or UUID.
|
|
142
|
+
|
|
143
|
+
- `metaData : Hash=nil` - An optional hash containing extra data about the user or environment to generate better results.
|
|
144
|
+
|
|
145
|
+
========
|
|
146
|
+
|
|
147
|
+
####Persistent MetaData
|
|
148
|
+
The DopamineKit object can hold some metaData that is stored and sent with all calls. This can be used in place of, or in addition to the `metaData` parameter for the `reinforce()` and `track()` calls.
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
#####Add or Update PersistentMetaData
|
|
152
|
+
Add or update some metaData that you want to include multiple reinforce/tracking calls.
|
|
153
|
+
|
|
154
|
+
######General syntax
|
|
155
|
+
```
|
|
156
|
+
dopaminekit.addPersistentMetaData(key, value)
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
######Parameters:
|
|
160
|
+
- `key : String` - A descriptive name for the metaData
|
|
161
|
+
|
|
162
|
+
- `value : var` - A JSON compliant variable. For example, an Int, Float, String, array, or another Hash.
|
|
163
|
+
|
|
164
|
+
#####Get PersistentMetaData
|
|
165
|
+
Retrieve a copy of the persistentMetaData Hash. Can be modified and then put back using `setPersistentMetaData()`
|
|
166
|
+
|
|
167
|
+
######General syntax
|
|
168
|
+
```
|
|
169
|
+
dopaminekit.getPersistentMetaData()
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
######Returns:
|
|
173
|
+
- `Hash` - A copy of the persistentMetaData Hash.
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
#####Set PersistentMetaData
|
|
178
|
+
Replace all contents within the persistentMetaData Hash, and replace them with the Hash passed in.
|
|
179
|
+
|
|
180
|
+
######General syntax
|
|
181
|
+
```
|
|
182
|
+
dopaminekit.setPersistentMetaData(hash)
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
######Parameters:
|
|
186
|
+
- `hash : Hash` - A Hash of JSON compliant key-value pairs. For example, Ints, Floats, Strings, arrays, or other Hashes.
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
#####Clear PersistentMetaData
|
|
191
|
+
Clear all entries in the persistentMetaData Hash.
|
|
192
|
+
|
|
193
|
+
######General syntax
|
|
194
|
+
```
|
|
195
|
+
dopaminekit.clearPersistentMetaData()
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
========
|
|
26
199
|
|
|
27
200
|
## Development
|
|
28
201
|
|
|
@@ -32,7 +205,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
|
|
|
32
205
|
|
|
33
206
|
## Contributing
|
|
34
207
|
|
|
35
|
-
Bug reports and pull requests are welcome on GitHub at https://github.com/
|
|
208
|
+
Bug reports and pull requests are welcome on GitHub at [https://github.com/dopaminelabs/dopaminekit/issues](https://github.com/dopaminelabs/dopaminekit/issues). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
|
|
36
209
|
|
|
37
210
|
|
|
38
211
|
## License
|
data/lib/dopaminekit/version.rb
CHANGED
data/lib/dopaminekit.rb
CHANGED
|
@@ -6,12 +6,21 @@ require 'json'
|
|
|
6
6
|
class DopamineKit
|
|
7
7
|
|
|
8
8
|
##
|
|
9
|
+
# Creates a DopamineKit object to communicate with the DopamineAPI
|
|
9
10
|
# Get your credentials from dashboard.usedopamine.com and enter them during initilization
|
|
10
11
|
#
|
|
11
|
-
|
|
12
|
+
# Params:
|
|
13
|
+
# +appID+:: String - Uniquely identifies your app, get this from your [developer dashboard](http://dev.usedopamine.com).
|
|
14
|
+
# +developmentSecret+:: String - Secret key for development.
|
|
15
|
+
# +productionSecret+:: String - Secret key for production.
|
|
16
|
+
# +versionID+:: String - This is a unique identifier that you choose that marks this implementation as unique in our system. This could be something like 'summer2015Implementation' or 'ClinicalTrial4'. Your `versionID` is what we use to keep track of what users are exposed to what reinforcement and how to best optimize that.
|
|
17
|
+
# +inProduction+:: boolean - Indicates whether app is in production or development mode, when you're happy with how you're integrating Dopamine and ready to launch set this argument to `true`. This will activate optimized reinforcement and start your billing cycle. While set to `false` your app will receive dummy reinforcement, new users will not be registered with our system, and no billing occurs.
|
|
18
|
+
# +debugMode+:: boolean=false - Enables debug mode, where the sent and received data are printed. Can be updated with `enableDebugMode(bool)`.
|
|
19
|
+
#
|
|
20
|
+
def initialize(appID, developmentSecret, productionSecret, versionID, inProduction, debugMode=false)
|
|
12
21
|
@clientSDKVersion = '3.0.0'
|
|
13
22
|
@persistentMetaData = Hash.new
|
|
14
|
-
@debugMode =
|
|
23
|
+
@debugMode = debugMode
|
|
15
24
|
|
|
16
25
|
@credentials = {
|
|
17
26
|
:appID => appID,
|
|
@@ -20,30 +29,42 @@ class DopamineKit
|
|
|
20
29
|
}
|
|
21
30
|
end
|
|
22
31
|
|
|
32
|
+
##
|
|
33
|
+
# When debugMode is set to true, the raw sent and received data are printed.
|
|
34
|
+
# It is by default set to false.
|
|
35
|
+
#
|
|
36
|
+
# Params:
|
|
37
|
+
# +enabled+:: boolean - true to enable, false to disable
|
|
38
|
+
#
|
|
39
|
+
def enableDebugMode(enabled)
|
|
40
|
+
@debugMode = enabled
|
|
41
|
+
end
|
|
42
|
+
|
|
23
43
|
##
|
|
24
44
|
# Used to send tracking calls to the DopamineAPI.
|
|
25
|
-
# actionID - a descriptive name for an action or behavior to be tracked
|
|
26
|
-
# identity - a string used an identifier for anonymized experiments
|
|
27
|
-
# metaData - a hash of metadata to get better experiment results.
|
|
28
|
-
# Can be set to 'nil'
|
|
29
45
|
#
|
|
30
|
-
#
|
|
31
|
-
#
|
|
46
|
+
# Params:
|
|
47
|
+
# +actionID+:: String - A descriptive name for action that the user has performed
|
|
48
|
+
# +identity+:: String - A string used to identify a particular user, such as an email or username or UUID.
|
|
49
|
+
# +metaData+:: Hash=nil - A hash containing extra data about the user or environment to generate better results.
|
|
50
|
+
#
|
|
51
|
+
# Return:
|
|
52
|
+
# +response+:: JSON - contains a key 'status', and if 'status' != 200 the object also contains another key 'errors'
|
|
32
53
|
#
|
|
33
|
-
def track(actionID, identity, metaData)
|
|
54
|
+
def track(actionID, identity, metaData=nil)
|
|
34
55
|
if !actionID.is_a? String
|
|
35
|
-
puts "[DopamineKit] - Invalid actionID
|
|
56
|
+
puts "[DopamineKit] - Invalid actionID for tracking call:#{actionID}"
|
|
36
57
|
return
|
|
37
58
|
end
|
|
38
59
|
if !identity.is_a? String
|
|
39
|
-
puts "[DopamineKit] - Invalid identity
|
|
60
|
+
puts "[DopamineKit] - Invalid identity for tracking call:#{identity}"
|
|
40
61
|
return
|
|
41
62
|
end
|
|
42
63
|
|
|
43
64
|
postData = getBasePostData()
|
|
44
65
|
postData[:actionID] = actionID
|
|
45
66
|
postData[:primaryIdentity] = identity
|
|
46
|
-
if(metaData
|
|
67
|
+
if(metaData != nil and metaData.is_a? Hash)
|
|
47
68
|
postData[:metaData] = metaData.merge(@persistentMetaData){|key, meta, persistentmeta| meta}
|
|
48
69
|
else
|
|
49
70
|
postData[:metaData] = @persistentMetaData
|
|
@@ -56,21 +77,22 @@ class DopamineKit
|
|
|
56
77
|
|
|
57
78
|
##
|
|
58
79
|
# Used to send reinforcement calls to the DopamineAPI.
|
|
59
|
-
#
|
|
60
|
-
#
|
|
61
|
-
#
|
|
62
|
-
#
|
|
63
|
-
#
|
|
64
|
-
#
|
|
65
|
-
#
|
|
80
|
+
#
|
|
81
|
+
# Params:
|
|
82
|
+
# +actionID+:: String - A descriptive name for action that the user has performed
|
|
83
|
+
# +identity+:: String - A string used to identify a particular user, such as an email or username or UUID.
|
|
84
|
+
# +metaData+:: Hash=nil - A hash containing extra data about the user or environment to generate better results.
|
|
85
|
+
#
|
|
86
|
+
# Return:
|
|
87
|
+
# +response+:: String - the reinforcement decision, picked from a set declared on the Dopamine Developer Dashboard
|
|
66
88
|
#
|
|
67
|
-
def reinforce(actionID, identity, metaData)
|
|
89
|
+
def reinforce(actionID, identity, metaData=nil)
|
|
68
90
|
if !actionID.is_a? String
|
|
69
|
-
puts "[DopamineKit] - Invalid actionID
|
|
91
|
+
puts "[DopamineKit] - Invalid actionID for reinforcement call:#{actionID}"
|
|
70
92
|
return
|
|
71
93
|
end
|
|
72
94
|
if !identity.is_a? String
|
|
73
|
-
puts "[DopamineKit] - Invalid identity
|
|
95
|
+
puts "[DopamineKit] - Invalid identity for reinforcement call:#{identity}"
|
|
74
96
|
return
|
|
75
97
|
end
|
|
76
98
|
|
|
@@ -78,7 +100,7 @@ class DopamineKit
|
|
|
78
100
|
postData = getBasePostData()
|
|
79
101
|
postData[:actionID] = actionID
|
|
80
102
|
postData[:primaryIdentity] = identity
|
|
81
|
-
if(metaData
|
|
103
|
+
if(metaData != nil and metaData.is_a? Hash)
|
|
82
104
|
postData[:metaData] = metaData.merge(@persistentMetaData){|key, meta, persistentmeta| meta}
|
|
83
105
|
else
|
|
84
106
|
postData[:metaData] = @persistentMetaData
|
|
@@ -95,9 +117,13 @@ class DopamineKit
|
|
|
95
117
|
|
|
96
118
|
|
|
97
119
|
##
|
|
98
|
-
#
|
|
120
|
+
# .
|
|
99
121
|
# Use setPersistentMetaData() to replace the entire persistentMetaData hashtable,
|
|
100
122
|
# and use clearPersistentMetaData() to clear it.
|
|
123
|
+
#
|
|
124
|
+
# Params:
|
|
125
|
+
# +key+:: String - A descriptive name for the metaData
|
|
126
|
+
# +value+:: var - A JSON compliant variable
|
|
101
127
|
#
|
|
102
128
|
def addPersistentMetaData(key, value)
|
|
103
129
|
@persistentMetaData[key.to_sym] = value
|
|
@@ -106,6 +132,9 @@ class DopamineKit
|
|
|
106
132
|
##
|
|
107
133
|
# Replace all contents within the persistentMetaData hash,
|
|
108
134
|
# and replace them with the hash passed in
|
|
135
|
+
#
|
|
136
|
+
# Params:
|
|
137
|
+
# +hash+:: Hash - A hash of JSON compliant key-value pairs
|
|
109
138
|
#
|
|
110
139
|
def setPersistentMetaData(hash)
|
|
111
140
|
if hash.is_a? Hash
|
|
@@ -114,14 +143,14 @@ class DopamineKit
|
|
|
114
143
|
end
|
|
115
144
|
|
|
116
145
|
##
|
|
117
|
-
# Clear all entries
|
|
146
|
+
# Clear all entries in the persistentMetaData hash.
|
|
118
147
|
#
|
|
119
148
|
def clearPersistentMetaData()
|
|
120
149
|
@persistentMetaData.clear
|
|
121
150
|
end
|
|
122
151
|
|
|
123
152
|
##
|
|
124
|
-
#
|
|
153
|
+
# Retrieve a copy of the persistentMetaData hash.
|
|
125
154
|
#
|
|
126
155
|
def getPersistentMetaData()
|
|
127
156
|
return @persistentMetaData.clone
|