*Stellantis Connected Vehicles SDK runs on iOS 12+ (and 13+ for some features) and Android 7+.

Bluetooth, GPS & internet connection might be required on the device, depending on the API.

Check out Access Requirements for info about connected services.

Initialize & Release #

First of all, before being able to request any API, you should initialize the SDK.

Initializing the SDK require configuration params details in the following table:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
pims.initialize(
  mapOf( /* parameters */  
    Pair("environnement", "Production"),
    Pair("mode", "B2B"),
    Pair("monitoring", map0f(
      Pair("logLevel", "low"),
      Pair("newLogFile", "appLaunch"),
      Pair("newLogTimeDuration", 42)
    )
    Pair("credential", map0f(
      Pair("clientId", "6779ef20e75817b79602"),
      Pair("clientSecret", "865333ef347etr"),
      Pair("macID", "macIDValue"),
      Pair("inWeboURL", "https://address.tld"),
      Pair("webviewsRedirectURI", "https://address.tld"),
      Pair("loginRedirectURI", "https://address.tld")
    )
    Pair("profile", map0f(
      Pair("brand", "opel")
    )
  )
) { /* Callback */
  message -> when (message["status"] as? String) {
    "SUCCEEDED" -> { }                          // handle succeeded initialization
    "FAILED" ->    { }                          // handle failed initialization
} }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
pims.initialize(
  parameters: [  
    "environnement": "Production",
    "mode": "B2C",
    "monitoring": [
      "logLevel": "low",
      "newLogFile": "appLaunch",
      "newLogTimeDuration": 42
    ],
    "credential": [
      "clientId": "6779ef20e75817b79602",
      "clientSecret": "865333ef347etr",
      "macID": "macIDValue",
      "inWeboURL": "https://addres.tlhttps://address.tld",
      "webviewsRedirectURI": "https://address.tld",
      "loginRedirectURI": "https://address.tld"
    ],
    "profile": [
      "brand": "opel"
    ] 
  ]
) { /* Callback */
  (message) in 
    if message["status"] == "SUCCEEDED"    { }    // handle succeeded initialization
    else if message["status"] == "FAILED" { }    // handle failed initialization
}

If you don’t need to use this SDK anymore, you can call the release method for performance reasons:

1
2
3
4
5
6
pims.release( /* No Parameters */ )
  { /* Callback */
  message -> when (message["status"] as? String) {
    "SUCCEEDED" -> { }                          // handle succeeded release
    "FAILED" ->    { }                          // handle failed release
  } }

1
2
3
4
5
6
pims.release( /* No Parameters */ ) 
  { /* Callback */
  (message) in 
    if message["status"] == "SUCCEEDED"    { }    // handle succeeded release
    else if message["status"] == "FAILED" { }    // handle failed release
  }

Once the SDK is set up, either for Android or iOS, it’s possible to perform your first API request!

Depending on the API, you need first to perform the appropriate security steps. Read security for more information about these security schemes.

API Methods #

Four methods are available depending on the API:

1
2
3
4
5
6
7
8
/* request data*/
pims.get()

/* change data */
pims.set()

/* subscribe (or unsubscribe) to events */
pims.subscribe() /* and */ pims.unsubscribe()

Each API can exist under these 4 types. See References for the list of all APIs and their types.

Method Get & Set #

Get & Set Request

This is an example of a Get request, but a Set is the same format. Once requested, this API will return only one return message.

• GET method of an API will return the requested data, just after the method is requested.
• SET method of an API will change the data in the system and return an acknowledgment message, this message might also include data.

1
2
3
4
5
6
7
8
9
10
11
12
13
/* Method Get */
pims.get(
  /* -- API Name -- */
  "pims.vehicle.price",
  /* -- API Parameters -- */
  mapOf( 
    Pair("vin", "VR1AB12C3D4567890")
  ) 
) { /* -- API Callback -- */
    message -> when (message["status"] as? String) {
      "SUCCEEDED" -> { }                          // handle succeeded status
      "FAILED" ->    { }                          // handle failed status
  } }

1
2
3
4
5
6
7
8
9
10
11
12
13
/* Method Get */
pims.get(
  /* -- API Name -- */
  api: "pims.vehicle.price",
  /* -- API Parameter -- */
  parameters: [  
    "vin": "VR1AB12C3D4567890"
  ]
  ) { /* -- API Callback -- */
      (message) in 
        if message["status"] == "SUCCEEDED"    { }    // handle succeeded status
        else if message["status"] == "FAILED" { }    // handle failed status
    }

Let’s explain this request example:

• API Name - String - The name of the API to request.
• API Parameters - Object - Parameters specific to this API. Parameters and outputs are available in references.
• API Callback - Function - Code to execute when a message is received.

Get & Set Callback

After requesting an API of the Get & Set type, you should except one return between 2 kinds of messages. That’s why your callback should be able to handle both these possibilities:

•   Succeeded This message is returned when the operation has been executed successfully.
•   Failed This message is received when the operation failed.

1
2
3
4
5
6
7
8
9
10
11
// SUCCEEDED: representation of the natif dictionary object message as JSON
// This message is the response to a get/set method in case of success
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED"
  /* Set APIs might not include a result field */
  "result": { 
    "priceFuel": "1.27",
    "priceElectric": "0.85"
  } 
}

1
2
3
4
5
6
7
8
9
10
// FAILED: representation of the natif dictionary object message as JSON
// This message is the response to a get/set method in case of failure
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": "2000",
    "label": "Unknown error"
  }
}

The previous example is the JSON representation of the returned message object. This table details the message structure:

Method Subscribe #

Subscribe Request

Here is the example of a Subscribe request. Once subscribed, this example API will return events each time the vehicle stop charging. Subscribe APIs are returning multiple messages.

• SUBSCRIBE method of an API will return the requested data each time the value change in the system.
• UNSUBSCRIBE method of an API will stops messages from triggering callbacks.

Re-Subscribe: If you try to subscribe twice to the same API, you’ll receive error 2005: Duplicate command.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/* Method Subscribe */
pims.subscribe(
  /* -- API Name -- */
  "pims.vehicle.event",
  /* -- API Parameters -- */
  mapOf( 
    Pair("actionType", "remote"),
    Pair("type", mapOf("remoteChargeFinished", "remoteChargeInterrupted"))
  ) 
) { /* -- API Callback -- */
    message -> when (message["status"] as? String) {
      "SUCCEEDED" -> { }                          // handle succeeded status
      "FAILED" ->    { }                          // handle failed status
      "RESULT" ->    {
        if(message["error"] != null) { }            // handle error event code
        else { }                                 // handle result event code
      }
  } }

/* Method Unsubscribe */
pims.unsubscribe( "pims.vehicle.event" /* no params */ ) { /* API Callback */ }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
/* Method Subscribe */
pims.subscribe(
  /* -- API Name -- */
  api: "pims.vehicle.event",
  /* -- API Parameter -- */
  parameters: [  
    "actionType": "remote",
    "type": ["remoteChargeFinished", "remoteChargeInterrupted"]
  ]
  ) { /* -- API Callback -- */
      (message) in 
        if message["status"] == "SUCCEEDED"    { }    // handle succeeded status
        else if message["status"] == "FAILED" { }    // handle failed status
        else if status == "RESULT" {
          if !message["error"].isEmpty { }            // handle error event code
          else { }                                    // handle result event code
        }
    }

/* Method Unsubscribe */
pims.unsubscribe( api: "pims.vehicle.event" /* no params */ ) { /* API Callback */ }

Let’s explain this request example:

• API Name - String - The name of the API to request.
• API Parameters - Object - Parameters specific to this API. Parameters and outputs are available in references.
• API Callback - Function - Code to execute when a message is received.

Subscribe Callback

After requesting an API of the subscribe type, you should except 3 kind of messages. That’s why your callback should be able to handle all these possibilities:

•   Succeeded This message is received only once, it acknowledge that the subscription is successful.
•   Failed This message is received only once, it acknowledge that the subscription failed.
•   Result This message is received each time the event is triggered for this subscribe. It includes response data of the subscribed API.

when the subscribe is in error, the subscription has not been taken in account, no event will follow. In this case the message include the error field with error info.

1
2
3
4
5
6
7
// SUCCEEDED: representation of the natif dictionary object message as JSON
// This message aknowledge that the subscribe has been taken in account
// 'result' messages will follow
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED"
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// RESULT: representation of the natif dictionary object message as JSON
// these messages are returned each time an normal event or error is triggered

//       -- Event message of a normal result -- 
// subscription doesn't stop and other messages will follow
{
  "transactionId": "953cfefb-bc72",
  "status": "RESULT",
  "result": {
    "event": "migrationBegin"
  }
}
//          -- Event message of an error -- 
// subscription doesn't stop and other messages will follow
{
  "transactionId": "953cfefb-bc72",
  "status": "RESULT",
  "error": {
    "code": "2000",
    "label": "Unknown error"
  }
}

1
2
3
4
5
6
7
8
9
10
11
// FAILED: representation of the natif dictionary object message as JSON
// This message is returned when an error occurred, the subscription failed,
// no other messages will follow.
{
  "transactionId": "953cfefb-bc72",
  "status": "FAILED",
  "error": {
    "code": "2000",
    "label": "Unknown error"
  }
}

The previous example is the JSON representation of the returned message object. This table details the message structure: