Services

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

Caret Services

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.

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.

Check out our Caret Slack Service or Android sample application or the Caret provided bots as an example.

About

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:

  • register a new service in the Caret Web Communicator
  • develop your new service
  • ask Caret users to consent your service
  • start publishing custom status information!

xwiki_about.png

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.

Register the new service

Képernyőfotó 2016-12-02 - 13.33.14.png

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.
NOTE: Please make sure you installed Caret client on your smart device first and registered your phone number.

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:

Képernyőfotó 2016-12-02 - 14.04.32.png

 

In order to see your own services, or to create a new one, click on 'My Services':

Képernyőfotó 2016-12-02 - 14.07.21.png

 

Under 'My Services' you get detailed information on your services: their name, a short description, the current status of your service, and available actions.

A service can have the following states:

  • 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)
  • 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  
  • 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
  • published: your service is open for the public.

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.

Adding a new service

A new service can be added by clicking on the green plus icon. You'll get a form similar to the following:

Képernyőfotó 2016-12-02 - 14.17.04.png

The form is straightforward, just enter:

  • 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
  • Access URL: a URL through which users can get detailed information on the service
  • Description: a slightly more detailed information on your service that the name provides.

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.

OK, so we have created the service:

Képernyőfotó 2016-12-02 - 14.21.33.png

Get service details

Once you've created a service, you can get detailed information about it by clicking on its name:

Képernyőfotó 2016-12-02 - 14.23.25.png

This is very similar to the new service form, but you get some additional details at the top:

  • 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
  • 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.
  • 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. 

Developing your service

Now you have every detail about your service. Let's implement it! These are the main steps to have a fully functional service:

  1. Enable Caret integration for your service (appinit)
  2. Ask Caret users for approving your service (service consent)
  3. Publish custom status information
  4. Stop your service
  5. (Disable Caret integration for your service (appdelete))

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!

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.

Enable Caret integration for your service (appinit)

By using this call you tell Caret that your service will actually publish call statuses in the future. The API call is really simple:

$ 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
{
 "uuid": "FFC48F52-A5F8-4901-B9E8-7E82A815236D"
}
Dead simple JSON POST request. The variable you have to substitute are the followings:
  • <service_id>: the ID of your service
  • <service_secret>: the secret key of your service
  • <phone_number>: the phone number you've used to register in the Caret Web Communicator.

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.

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.

Ask Caret users for approving your service (service consent)

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.

The task on iOS is to invoke the following URL: &uuid=">

The same functionality can be achieved on Android using this code snippet:

Intent intent = new Intent("com.wallrust.caret.intent.action.SERVICES");
intent.putExtra("service_id", "<service_id>");
intent.putExtra("name", "<name_of_service>");
intent.putExtra("uuid", "<appinit_id>");
startActivity(intent);

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.

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.

Publish custom status information

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.

Please read the following API descriptions first in order to understand how custom status publishing works:

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.

Finally, the curl command to publish a custom status is as follows:

$ 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
{
 "status": "published"
}

And here is an example JSON:

{
  "status": "gaming",
  "target": "<appinit_id>",
  "context": [
    {
      "text": "Gaming now with ",
      "link": {
        "text": "PuzzleWinds",
        "ios_uri": "https://itunes.apple.com/app/id1050414691",
        "android_uri": "http://www.puzzlewinds.com/"
      }
    },
    {
      "text": "Join current level ",
      "link": {
        "text": "now",
        "ios_uri": "puzzlewinds://currentioslevel",
        "android_uri": "puzzlewinds://currentandroidlevel"
      }
    }
  ],
  "app": {
    "text": "You can download from ",
    "link": {
      "android": {
        "text": "PuzzleFlow website",
        "uri": "http://www.puzzlewinds.com/"
      },
      "ios": {
        "text": "App Store",
        "uri": "https://itunes.apple.com/app/id1050414691"
      }
    }
  }
}

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:

Képernyőfotó 2016-12-02 - 15.56.03.png

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.

Isn't it nice?

While the user is playing with your game, it is recommended to publish call status at least every 10 minutes.

Stop your service

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.

The REST call is the following:

$ 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
{
 "status": "published"
}

This is a traditional status call, with 'status' set to 'service-off'.

Service SDKs

We are actively working on iOS and Android SDKs. If you are interested in Caret Service SDKs, then contact us at support@caretapp.com

Details about an Android sample application using Caret's public APIs can be found in this page.

Tags:
Created by Zoltan Farkas on 2016/12/01 23:18