Wiki source code of Services

Last modified by editor on 2017/12/03 07:32

Hide last authors
Zoltan Farkas 1.1 1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 = Caret Services =
6
Zoltan Farkas 26.1 7 This page describes how to use the Caret infrastructure for building [[services>>https://caret.co/services.html]] enabling you to publish custom status information. Caret's [[Application Programming Interface>>https://caret.co/caret-api/]] (API) lets users harness their smart device sensors and interconnect them with third party devices & applications to automate customizable status sharing services. Users can share what they are doing in one app when they are doing it via an interactive Caret status. Your status could automatically change when you start playing a game and contain a link, photo and more about that game. For more complex cross-app or sensor triggered statuses, you can order custom built solutions through Caret’s [[Web Communicator>>https://portal.caret.co/]].
editor 15.2 8
Zoltan Farkas 19.1 9 Companies can connect their business logic and promotions to enhance their B2C or B2B needs. For example, when users start playing [[PuzzleWinds>>http://www.puzzlewinds.com/]], their statuses change to 'Playing PuzzleWinds - join me!'. Companies can also customize additional status personalisation services by integrating their app’s business logic with Caret’s multiple modules.
editor 27.4 10
editor 38.1 11 Check out our [[Caret Slack Service>>url:https://slack.com/apps/A7N6GFB7A-caret-service]] or Android [[sample application>>https://xwiki.caret.co/bin/view/Services/Android/]] or the Caret provided [[bots>>doc:Caret-bots.WebHome]] as an example.
Zoltan Farkas 1.1 12 )))
13 )))
14
15 (% class="row" %)
16 (((
17 (% class="col-xs-12 col-sm-8" %)
18 (((
19 = About =
20
editor 16.1 21 In this article we will go through all the necessary steps to have a complete service for publishing custom status information with your existing iOS or Android application. The main steps are the following:
Zoltan Farkas 1.1 22
editor 17.1 23 * register a new service in the Caret Web Communicator
Zoltan Farkas 1.1 24 * develop your new service
25 * ask Caret users to consent your service
Zoltan Farkas 8.2 26 * start publishing custom status information!
Zoltan Farkas 1.1 27
Zoltan Farkas 13.2 28 (% style="text-align:center" %)
Zoltan Farkas 23.1 29 [[image:xwiki_about.png||height="536" width="800"]]
Zoltan Farkas 8.2 30
Zoltan Farkas 25.1 31
Zoltan Farkas 19.1 32 The overview of how services work to publish status information on behalf of the user is shown in the above figure. First, the service developer has to create the service on the [[Caret Web Communicator>>https://portal.caret.co/]] site. Afterwards, the logic of the service needs to be developed. Once the service is complete, it can be published through the Caret Web Communicator for the wider audience. From this point on, the service may publish customized status information for every Caret user two has allowed the service to do so. This can be performed with the help of the Android and iOS Caret application. After the service consent was given for a phone number, the custom status published by the service will be seen by the friends of the phone number.
Zoltan Farkas 13.2 33
Zoltan Farkas 8.2 34 = Register the new service =
35
Zoltan Farkas 13.2 36 (% style="text-align:center" %)
37 [[image:Képernyőfotó 2016-12-02 - 13.33.14.png||height="548" width="640"]]
Zoltan Farkas 8.2 38
Zoltan Farkas 18.1 39 First, log in to the [[Caret Web Communicator>>https://portal.caret.co/]] as shown in the above figure. You can use either Facebook or Google-based authentication. After logging in, if you're using the portal for the first time, you'll have to register your phone number. For this, set your phone number, and click 'Text PIN code'. You'll receive a PIN code shortly, please enter the given code on the next page. If you specify the received PIN code correctly, your phone number will be added to the Caret Web Communicator.
Zoltan Farkas 20.1 40 NOTE: Please make sure you installed [[Caret>>https://caret.co/]] client on your smart device first and registered your phone number.
Zoltan Farkas 13.2 41
Zoltan Farkas 8.2 42 After logging in you'll see the list of published services by default. These are the services that have already been developed, and are offered for public usage:
43
44 (% style="text-align:center" %)
45 (((
Zoltan Farkas 13.2 46 (% style="text-align:center" %)
47 [[image:Képernyőfotó 2016-12-02 - 14.04.32.png||height="308" width="640"]]
48
49
Zoltan Farkas 8.2 50 )))
51
52 In order to see your own services, or to create a new one, click on 'My Services':
53
54 (% style="text-align:center" %)
55 (((
Zoltan Farkas 13.2 56 (% style="text-align:center" %)
57 [[image:Képernyőfotó 2016-12-02 - 14.07.21.png||height="357" width="801"]]
58
59
Zoltan Farkas 8.2 60 )))
61
Zoltan Farkas 18.1 62 Under 'My Services' you get detailed information on your services: their name, a short description, the current status of your service, and available actions.
Zoltan Farkas 8.2 63
64 A service can have the following states:
65
66 * development: in this phase you are the only one who sees and can use the service. In this state, you can either submit your service for approval (by clicking on the green eye icon) or you can delete your service (by clicking on the orange trash icon)
67 * pending: your service will enter this state if you submit it for approval. The Caret team will be notified on your publish request, and start to check your service
Zoltan Farkas 18.1 68 * private: if the approval was successful, your service will enter this state. By using the green eye icon, you can publish your service from this state
Zoltan Farkas 8.2 69 * published: your service is open for the public.
70
71 Please note that anytime, if you click on your service, and edit its details, it will enter the development phase. Also, you can delete your service anytime if you want to by using the orange trash icon.
72
73 == Adding a new service ==
74
75 A new service can be added by clicking on the green plus icon. You'll get a form similar to the following:
76
77 (% style="text-align:center" %)
78 (((
Zoltan Farkas 13.2 79 (% style="text-align:center" %)
80 [[image:Képernyőfotó 2016-12-02 - 14.17.04.png||height="357" width="800"]]
Zoltan Farkas 8.2 81 )))
82
83 The form is straightforward, just enter:
84
85 * Name: a name for your service. Users will see this if your service asks for their approval to submit customized status information for their phone numbers
86 * Access URL: a URL through which users can get detailed information on the service
Zoltan Farkas 18.1 87 * Description: a slightly more detailed information on your service that the name provides.
Zoltan Farkas 8.2 88
Zoltan Farkas 18.1 89 You have the possibility to upload an icon for your service. You can also hide the phone number behind your service, so it will be searchable only by its name.
Zoltan Farkas 8.2 90
91 OK, so we have created the service:
92
Zoltan Farkas 13.2 93 (% style="text-align:center" %)
94 [[image:Képernyőfotó 2016-12-02 - 14.21.33.png||height="357" width="800"]]
Zoltan Farkas 8.2 95
96 == Get service details ==
97
Zoltan Farkas 9.2 98 Once you've created a service, you can get detailed information about it by clicking on its name:
Zoltan Farkas 8.2 99
Zoltan Farkas 13.2 100 (% style="text-align:center" %)
101 [[image:Képernyőfotó 2016-12-02 - 14.42.24.png||alt="Képernyőfotó 2016-12-02 - 14.23.25.png" height="571" width="799"]]
Zoltan Farkas 9.2 102
103
104 This is very similar to the new service form, but you get some additional details at the top:
105
106 * Service ID: this is the unique identifier of your service. If you want to use the Caret Infrastructure in the name of your service, you have to use this identifier to specify who you are
Zoltan Farkas 10.2 107 * Service Secret Key: this is the 'password' of your service. When accessing the Caret Infrastructure, you have to provide this secret along with the Service ID so Caret knows that it is really the service who is connecting. Click on 'Show' to reveal you service's secret key.
Zoltan Farkas 9.2 108 * Mobile app callback URL: this is an autogenerated URL scheme, the mobile Caret apps will use this URL to invoke your service (if it's also implemented as a mobile app) after the service consent has been approved by the user.
109
Zoltan Farkas 10.2 110 = Developing your service =
111
112 Now you have every detail about your service. Let's implement it! These are the main steps to have a fully functional service:
113
114 1. Enable Caret integration for your service (appinit)
115 1. Ask Caret users for approving your service (service consent)
116 1. Publish custom status information
Zoltan Farkas 13.1 117 1. Stop your service
Zoltan Farkas 10.2 118 1. (Disable Caret integration for your service (appdelete))
119
120 In our example we're creating a mobile game app, which will publish a custom status containing the link to the app in Play Store and the App Store, and will also contain a link through which other users can join the game you're playing!
121
Zoltan Farkas 18.1 122 The above mentioned steps will be implemented as REST API calls to the Caret API. For simplicity, we'll show [[curl>>https://curl.haxx.se/]] command line examples, which should be straightforward to implement in the programming language you're using.
Zoltan Farkas 10.2 123
124 == Enable Caret integration for your service (appinit) ==
125
Zoltan Farkas 18.1 126 By using this call you tell Caret that your service will actually publish call statuses in the future. The API call is really simple:
Zoltan Farkas 10.2 127
Zoltan Farkas 18.1 128 {{code}}
129 $ curl -X POST -u <service_id>:<service_secret> --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{}' https://prod-api.caret.co/api/v1.0/services/<phone_number>/appinit
130 {
131 "uuid": "FFC48F52-A5F8-4901-B9E8-7E82A815236D"
132 }
133 {{/code}}
Zoltan Farkas 10.2 134
Zoltan Farkas 14.1 135
Zoltan Farkas 18.1 136 {{{Dead simple JSON POST request. The variable you have to substitute are the followings:}}}
Zoltan Farkas 10.2 137
138 * <service_id>: the ID of your service
139 * <service_secret>: the secret key of your service
140 * <phone_number>: the phone number you've used to register in the Caret Web Communicator.
141
Zoltan Farkas 10.3 142 You can check the HTTP status code, if everything is OK, it should be 200. If something is wrong, check the Service ID, the Service Secret Key and the phone number.
Zoltan Farkas 10.2 143
Zoltan Farkas 10.3 144 As response, you'll receive a UUID, the appinit ID. Please note this UUID. Inside our gaming app, we can store this in some file.
Zoltan Farkas 1.1 145
Zoltan Farkas 10.3 146 == Ask Caret users for approving your service (service consent) ==
147
148 As next step, we need to pass the control to the Caret app on the mobile device with the information of our service so the user can decide if she allows our service to publish customized status info.
149
editor 37.2 150 The task on iOS is to invoke the following URL: [[&uuid=">>>caret://v1/serviceconsent?service_id=<service_id>&uuid=<appinit_id>]]
Zoltan Farkas 10.3 151
Zoltan Farkas 11.2 152 The same functionality can be achieved on Android using this code snippet:
Zoltan Farkas 10.3 153
Zoltan Farkas 18.1 154 {{code language="java"}}
Zoltan Farkas 10.3 155 Intent intent = new Intent("com.wallrust.caret.intent.action.SERVICES");
156 intent.putExtra("service_id", "<service_id>");
157 intent.putExtra("name", "<name_of_service>");
158 intent.putExtra("uuid", "<appinit_id>");
Zoltan Farkas 11.2 159 startActivity(intent);
Zoltan Farkas 18.1 160 {{/code}}
Zoltan Farkas 10.3 161
Zoltan Farkas 11.2 162 These will make the Service Consent Dialog of the Caret app appear, on which the user will be able to select the her phone numbers for which she wants to enable your service to publish call statuses for.
Zoltan Farkas 10.3 163
Zoltan Farkas 24.1 164 Once the Service Consent Dialog finishes, and the Caret app performs the necessary calls with the REST API, control will be given back to your app. Note for iOS developers: the Caret App will invoke the 'Mobile app callback URL' of your service, extended with the serviceconsent?approved=true or serviceconsent?approved=false depending on the choice of the user (approved or cancelled the Service Consent Dialog). So, for example, your app will receive back the control from Caret after invoking [[caret123://serviceconsent?approved=true]].
Zoltan Farkas 10.3 165
Zoltan Farkas 13.1 166 == Publish custom status information ==
Zoltan Farkas 11.2 167
Zoltan Farkas 13.1 168 Once the user has approved the Service Consent Dialog, you can start publishing custom status information. This will be a bit tricky, but if you copy-paste the JSON from here, and modify it according to your needs, you should be OK.
Zoltan Farkas 11.2 169
Zoltan Farkas 13.1 170 Please read the following API descriptions first in order to understand how custom status publishing works:
Zoltan Farkas 1.1 171
Zoltan Farkas 13.1 172 * [[Set phone number's status>>https://caret.co/caret-api/#!/status/put_api_v1_0_users_phonenumber_status]]
Zoltan Farkas 18.1 173 * [[Contextualised status information>>https://caret.co/caret-api/#!/context/put_api_v1_0_users_phonenumber_context]]
Zoltan Farkas 1.1 174
Zoltan Farkas 13.1 175 Simple enough? Well, the JSON is a bit chatty, but enables you to show different links to your game app for users watching your custom published status on iOS and Android (App Store and Play Store links, respectively) Caret apps.
Zoltan Farkas 1.1 176
Zoltan Farkas 13.1 177 Finally, the curl command to publish a custom status is as follows:
Zoltan Farkas 1.1 178
Zoltan Farkas 18.1 179 {{code}}
180 $ curl -X POST -u <service_id>:<service_secret> --header 'Content-Type: application/json' --header 'Accept: application/json' -d '<that_very_long_json>' https://prod-api.caret.co/api/v1.0/services/<phone_number>/status
181 {
182 "status": "published"
Zoltan Farkas 13.2 183 }
Zoltan Farkas 18.1 184 {{/code}}
Zoltan Farkas 1.1 185
Zoltan Farkas 13.1 186 And here is an example JSON:
Zoltan Farkas 1.1 187
Zoltan Farkas 18.1 188 {{code}}
Zoltan Farkas 13.1 189 {
190 "status": "gaming",
191 "target": "<appinit_id>",
192 "context": [
193 {
194 "text": "Gaming now with ",
195 "link": {
196 "text": "PuzzleWinds",
Zoltan Farkas 18.1 197 "ios_uri": "https://itunes.apple.com/app/id1050414691",
198 "android_uri": "http://www.puzzlewinds.com/"
Zoltan Farkas 13.1 199 }
200 },
201 {
202 "text": "Join current level ",
203 "link": {
204 "text": "now",
Zoltan Farkas 18.1 205 "ios_uri": "puzzlewinds://currentioslevel",
206 "android_uri": "puzzlewinds://currentandroidlevel"
Zoltan Farkas 13.1 207 }
208 }
209 ],
210 "app": {
211 "text": "You can download from ",
212 "link": {
213 "android": {
214 "text": "PuzzleFlow website",
Zoltan Farkas 18.1 215 "uri": "http://www.puzzlewinds.com/"
Zoltan Farkas 13.1 216 },
217 "ios": {
218 "text": "App Store",
Zoltan Farkas 18.1 219 "uri": "https://itunes.apple.com/app/id1050414691"
Zoltan Farkas 13.1 220 }
221 }
222 }
223 }
Zoltan Farkas 18.1 224 {{/code}}
Zoltan Farkas 1.1 225
Zoltan Farkas 13.1 226 If you publish status using this JSON, friends of the users who enabled you to publish the call status with the given appinit ID will see your status in the Caret app like this:
Zoltan Farkas 1.1 227
Zoltan Farkas 13.2 228 (% style="text-align:center" %)
Zoltan Farkas 13.1 229 [[image:Képernyőfotó 2016-12-02 - 15.56.03.png||height="702" width="432"]]
Zoltan Farkas 1.1 230
Zoltan Farkas 13.1 231 If users now click on the 'PuzzleWinds' click, they will be redirected either to the Play or App Store. If they click 'now', the PuzzleWinds game will open on their device given that it is installed.
Zoltan Farkas 1.1 232
Zoltan Farkas 13.1 233 Isn't it nice?
Zoltan Farkas 1.1 234
Zoltan Farkas 13.1 235 While the user is playing with your game, it is recommended to publish call status at least every 10 minutes.
236
237 == Stop your service ==
238
239 If the user leaves your game, you can tell Caret that you won't publish any new status recently, so the users' call status can be reverted back to the one before they started to use your game.
240
241 The REST call is the following:
242
Zoltan Farkas 18.1 243 {{code}}
Zoltan Farkas 24.1 244 $ curl -X PUT -u <service_id>:<service_secret> --header "Accept: application/json" -H "Content-type: application/json" -d '{"status":"service-off","target":"<appinit_id>"}' https://prod-api.caret.co/api/v1.0/services/<phonenumber>/status
Zoltan Farkas 18.1 245 {
246 "status": "published"
Zoltan Farkas 13.2 247 }
Zoltan Farkas 18.1 248 {{/code}}
Zoltan Farkas 13.1 249
250 This is a traditional status call, with 'status' set to 'service-off'.
editor 26.2 251
252 = Service SDKs =
253
editor 27.1 254 We are actively working on iOS and Android SDKs. If you are interested in Caret Service SDKs, then contact us at support@caretapp.com
255
editor 35.1 256 Details about an Android sample application using Caret's [[public APIs>>https://caret.co/caret-api/]] can be found in [[this page>>doc:.Android.WebHome]].
Zoltan Farkas 1.1 257 )))
258
259 (% class="col-xs-12 col-sm-4" %)
260 (((
261 {{box title="**Contents**"}}
262 {{toc /}}
263 {{/box}}
264
Zoltan Farkas 13.2 265
Zoltan Farkas 1.1 266 )))
267 )))