Wiki source code of Services

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

Show last authors
1 (% class="jumbotron" %)
2 (((
3 (% class="container" %)
4 (((
5 = Caret Services =
7 This page describes how to use the Caret infrastructure for building [[services>>]] enabling you to publish custom status information. Caret's [[Application Programming Interface>>]] (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>>]].
9 Companies can connect their business logic and promotions to enhance their B2C or B2B needs. For example, when users start playing [[PuzzleWinds>>]], 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.
11 Check out our [[Caret Slack Service>>url:]] or Android [[sample application>>]] or the Caret provided [[bots>>doc:Caret-bots.WebHome]] as an example.
12 )))
13 )))
15 (% class="row" %)
16 (((
17 (% class="col-xs-12 col-sm-8" %)
18 (((
19 = About =
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:
23 * register a new service in the Caret Web Communicator
24 * develop your new service
25 * ask Caret users to consent your service
26 * start publishing custom status information!
28 (% style="text-align:center" %)
29 [[image:xwiki_about.png||height="536" width="800"]]
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>>]] 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.
34 = Register the new service =
36 (% style="text-align:center" %)
37 [[image:Képernyőfotó 2016-12-02 - 13.33.14.png||height="548" width="640"]]
39 First, log in to the [[Caret Web Communicator>>]] 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.
40 NOTE: Please make sure you installed [[Caret>>]] client on your smart device first and registered your phone number.
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:
44 (% style="text-align:center" %)
45 (((
46 (% style="text-align:center" %)
47 [[image:Képernyőfotó 2016-12-02 - 14.04.32.png||height="308" width="640"]]
50 )))
52 In order to see your own services, or to create a new one, click on 'My Services':
54 (% style="text-align:center" %)
55 (((
56 (% style="text-align:center" %)
57 [[image:Képernyőfotó 2016-12-02 - 14.07.21.png||height="357" width="801"]]
60 )))
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.
64 A service can have the following states:
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
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
69 * published: your service is open for the public.
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.
73 == Adding a new service ==
75 A new service can be added by clicking on the green plus icon. You'll get a form similar to the following:
77 (% style="text-align:center" %)
78 (((
79 (% style="text-align:center" %)
80 [[image:Képernyőfotó 2016-12-02 - 14.17.04.png||height="357" width="800"]]
81 )))
83 The form is straightforward, just enter:
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
87 * Description: a slightly more detailed information on your service that the name provides.
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.
91 OK, so we have created the service:
93 (% style="text-align:center" %)
94 [[image:Képernyőfotó 2016-12-02 - 14.21.33.png||height="357" width="800"]]
96 == Get service details ==
98 Once you've created a service, you can get detailed information about it by clicking on its name:
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"]]
104 This is very similar to the new service form, but you get some additional details at the top:
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
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.
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.
110 = Developing your service =
112 Now you have every detail about your service. Let's implement it! These are the main steps to have a fully functional service:
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
117 1. Stop your service
118 1. (Disable Caret integration for your service (appdelete))
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!
122 The above mentioned steps will be implemented as REST API calls to the Caret API. For simplicity, we'll show [[curl>>]] command line examples, which should be straightforward to implement in the programming language you're using.
124 == Enable Caret integration for your service (appinit) ==
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:
128 {{code}}
129 $ curl -X POST -u <service_id>:<service_secret> --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{}'<phone_number>/appinit
130 {
131 "uuid": "FFC48F52-A5F8-4901-B9E8-7E82A815236D"
132 }
133 {{/code}}
136 {{{Dead simple JSON POST request. The variable you have to substitute are the followings:}}}
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.
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.
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.
146 == Ask Caret users for approving your service (service consent) ==
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.
150 The task on iOS is to invoke the following URL: [[&uuid=">>>caret://v1/serviceconsent?service_id=<service_id>&uuid=<appinit_id>]]
152 The same functionality can be achieved on Android using this code snippet:
154 {{code language="java"}}
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>");
159 startActivity(intent);
160 {{/code}}
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.
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]].
166 == Publish custom status information ==
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.
170 Please read the following API descriptions first in order to understand how custom status publishing works:
172 * [[Set phone number's status>>!/status/put_api_v1_0_users_phonenumber_status]]
173 * [[Contextualised status information>>!/context/put_api_v1_0_users_phonenumber_context]]
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.
177 Finally, the curl command to publish a custom status is as follows:
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>'<phone_number>/status
181 {
182 "status": "published"
183 }
184 {{/code}}
186 And here is an example JSON:
188 {{code}}
189 {
190 "status": "gaming",
191 "target": "<appinit_id>",
192 "context": [
193 {
194 "text": "Gaming now with ",
195 "link": {
196 "text": "PuzzleWinds",
197 "ios_uri": "",
198 "android_uri": ""
199 }
200 },
201 {
202 "text": "Join current level ",
203 "link": {
204 "text": "now",
205 "ios_uri": "puzzlewinds://currentioslevel",
206 "android_uri": "puzzlewinds://currentandroidlevel"
207 }
208 }
209 ],
210 "app": {
211 "text": "You can download from ",
212 "link": {
213 "android": {
214 "text": "PuzzleFlow website",
215 "uri": ""
216 },
217 "ios": {
218 "text": "App Store",
219 "uri": ""
220 }
221 }
222 }
223 }
224 {{/code}}
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:
228 (% style="text-align:center" %)
229 [[image:Képernyőfotó 2016-12-02 - 15.56.03.png||height="702" width="432"]]
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.
233 Isn't it nice?
235 While the user is playing with your game, it is recommended to publish call status at least every 10 minutes.
237 == Stop your service ==
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.
241 The REST call is the following:
243 {{code}}
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>"}'<phonenumber>/status
245 {
246 "status": "published"
247 }
248 {{/code}}
250 This is a traditional status call, with 'status' set to 'service-off'.
252 = Service SDKs =
254 We are actively working on iOS and Android SDKs. If you are interested in Caret Service SDKs, then contact us at
256 Details about an Android sample application using Caret's [[public APIs>>]] can be found in [[this page>>doc:.Android.WebHome]].
257 )))
259 (% class="col-xs-12 col-sm-4" %)
260 (((
261 {{box title="**Contents**"}}
262 {{toc /}}
263 {{/box}}
266 )))
267 )))