Mobile SDK

iOS or Android

    Overview - Get Started

    Info: Stellantis Mobile SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) is not publicly available for now.

    Stellantis Connected Vehicles SDK for ex Groupe PSA brands (Citroën, DS, Peugeot, Opel and Vauxhall) 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:

    Initialize SDK: Parameters
    Param name Description Type Unit/Values Example Required
    environnement

    Environnement value.

    String

    - Production

    - Preproduction

    - development
    Preproduction true
    mode

    Mode value.

    String

    - B2C

    - B2B
    B2C true
    monitoring

    Monitoring informations.

    Object

    / /
    credential

    Credential informations.

    Object

    / /
    profile

    Profile informations.

    Object

    / /
    Initialize SDK: Request Example
    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"] == "SUCEEDED"    { }    // 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:

    Release SDK: Request Example
    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"] == "SUCEEDED"    { }    // 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()
    
    Method Description Callback Outputted Data
    GET Allows requesting single time data. Only one callback, when the request has been resolved successfully or is in error. The message includes outputted data or info about the error.
    SET Allows changing a value or set up an action. Only one callback, when the request has been resolved or is in error. The message might be empty or includes outputted data or info about the error.
    SUBSCRIBE Allows receiving events when a data changes. An acknowledgment callback, when the request has been taken in account or is in error.
    Then, an event callback each time the event is triggered.
    The acknowledgment message does not include outputted data, but can include info in case of error.
    The event message include outputted data or info about error.
    UNSUBSCRIBE Whenever an api is available under the subscribe method, unsubscribe is also available to stop receiving events. Only one callback, when the request has been resolved or is in error. The message does not include outputted data, but can include info in case of error.

    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"] == "SUCEEDED"    { }    // handle succeeded status
            else if message["status"] == "FAILED" { }    // handle failed status
        }
    

    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:

    Name Value Description
    transactionId String Id of the request.
    status Enum of Strings Status of the message:
       • status:   Succeeded the operation has been executed successfully.
       • status:   Failed the operation is in error.
    result dictionary Object Contains the outputted data, see reference page for the output of each API.
       •   Succeeded Get operations always includes result, Set operations might include the result or not if no outputted data.
       •   Failed In Failed messages, this field is never returned.
    error dictionary Object Code and Label of the error, check-out reference page or error page for the list of errors.
       • Always returned in   Failed messages.
       • Never returned in   Succeeded messages.

    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"] == "SUCEEDED"    { }    // 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:

    Name Value Description
    transactionId String Id of the request, this is the same id for the Succeeded, Result and Failed, it’s useful to make sure of the origin of the message.
    status Enum of Strings Status of the message:
       • status:   Succeeded the subscription has been taken in account. Event messages with status result will be triggered.
       • status:   Result when a subscribe event is triggered (result or error). In this case the message include the result field with the outputted data or an error field error info.
       • status:   Failed the subscribe is in error, the subscription has not been taken in account, no event will follow.
    result dictionary Object Contains the outputted data, see reference page for the output of each API.
       •   Succeeded In Succeeded messages, this field is never returned
       •   Result In Result messages, this field is returned only when the field error is not returned.
       •   Failed In Failed messages, this field is never returned.
    error dictionary Object Code and Label of the error, check-out reference page or error page for the list of errors.
       •   Succeeded In Succeeded messages, this field is never returned
       •   Result In Result messages, this field is returned only when the field result is not returned.
       •   Failed In Failed messages, this field always returned.