Mobile SDK

iOS or Android

Security - Service Activation Steps

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

Security: Service Activation Steps require the following security schemes to be valid

References: check-out πŸ“‘ Steps component list of APIs.

Some API of this SDK require more than Authentication. The Step feature, provides guidance for additional security. It will return the list of Steps required to use a service.

First, you should request the list of Steps using a carAssociationID. Then, using the stepsID, you can update the list or retrieve only the next step to do.

Available Services #

This API cover the services required for remote component. They are two services required for remotes:

  • Vehicle Status: retrieve vehicle data like πŸš— vehicle VIN & brand, precond info, ⛽️ fuel info, πŸ”‹ electric info and πŸšͺ door state.
  • Remote Commands: allows using πŸ”“ lock/unlock, πŸ”‰ horn & πŸ’‘ lights, πŸ”Œ charge & ❄️ preconditioning.

Steps Name #

The following steps are the returned:

  • πŸ“± trustedPhone: The registration of a trusted phone is a preliminary step to device activation. See this page for detailed information.
  • πŸ“±βœ… deviceActivation: Activation of a device is a required security step, have a look at the dedicated tutorial.
  • πŸ”‘ mediumCarKey: This step allows making sure the user has the vehicle keys in their possession, see CarKey check.

Steps Status #

All steps have a status field that represent if the state is todo or alreadyDone.

When the status of a step is alreadyDone, there is no need to perform this security step again. When the status is todo, this security step is required for the service.

APIs returning a list of steps: pims.subscription.steps-carAssociationID & pims.subscription.steps-stepsID, have a parameter stepStatus, it will filter the step(s) based on their status:

  • todo: will only return steps required to unlock the service.
  • alreadyDone: will only return steps already checked.
  • all: will only return all steps.

Steps Order #

In the list of Steps returned in pims.subscription.steps-carAssociationID & pims.subscription.steps-stepsID, the order of the Steps matter!

You must follow the steps in the right to resolve the security checks successfully.

First List Request #

The first list of Steps must be requested using carAssociationID, then you can use StepsID for an updated list of steps or only for the next step.

carAssociationID: is not provided in this SDK. This code is available when subscribing to a connected service. A carAssociationID represents:

  • πŸ¦Έβ€β™‚οΈ An user.
  • πŸ’‘ Requesting a service.
  • πŸš— For a vehicle.

This API needs a carAssociationID, it will return the list of steps required for the service with their current status:

1
2
3
4
5
6
7
8
pims.get("pims.subscription.steps",
  mapOf( /* parameters */
  Pair("carAssociationID", "987654"),
  Pair("resetSteps", false),
  Pair("stepsStatus", "all")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.get(api: "pims.subscription.steps", 
  parameters: [
  "carAssociationID": "987654",
  "resetSteps": false,
  "stepsStatus": "all"
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { 
    "stepsID": 132324,
    "trustedPhone": {
        "name": "trustedPhone",
        "status": "alreadyDone",
        "order": 1
    },
    "deviceActivation": {
        "name": "deviceActivation",
        "status": "todo",
        "order": 2
    },
    "mediumCarKey": {
        "name": "mediumCarKey",
        "status": "todo",
        "order": 3
    }
  }
}

false

The stepsID returned in the result message allows to easily update this list.

Update the List #

After a first request with carAssociationID, you can use the stepsID to retrieve the updated list of steps. The stepsId is available in the return of the first List Request.

StepsID: this code can not be shared between devices, you should always use carAssociationID for the first request.

1
2
3
4
5
6
7
8
pims.get("pims.subscription.steps",
  mapOf( /* parameters */
  Pair("stepsID", "132324"),
  Pair("resetSteps", false),
  Pair("stepsStatus", "all")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
7
8
pims.get(api: "pims.subscription.steps", 
  parameters: [
  "stepsID": "132324",
  "resetSteps": false,
  "stepsStatus": "all"
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { 
    "stepsID": 132324,
    "trustedPhone": {
        "name": "trustedPhone",
        "status": "alreadyDone",
        "order": 1
    },
    "deviceActivation": {
        "name": "deviceActivation",
        "status": "todo",
        "order": 2
    },
    "mediumCarKey": {
        "name": "mediumCarKey",
        "status": "todo",
        "order": 3
    }
  }
}

false

Retrieve Next Step #

When you have access to stepsID, you can use the following API to return the next step in the list, this will return only one step at a time:

StepsID: this code can not be shared between devices, you should always use carAssociationID for the first request.

1
2
3
4
5
6
pims.get("pims.subscription.step",
  mapOf( /* parameters */
  Pair("stepsID", "132324")
  )
) { message -> /* handle message */ }
1
2
3
4
5
6
pims.get(api: "pims.subscription.step", 
  parameters: [
  "stepsID": "132324"
  ]
) { (message) in /* handle message */ }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// representation of the `succeeded` dictionary object message as JSON
{
  "transactionId": "953cfefb-bc72",
  "status": "SUCCEEDED",
  "result": { 
    // Example if next Step is deviceActivation
    "deviceActivation": {
      "name": "deviceActivation",
        "status": "todo",
        "order": 1
    }
    // Response is Null if there is no next step
  }
}

false

Cache #

Once a step reach the status alreadyDone in pims.vehicle.steps, the step will remain in the same status unless if the cache is wiped. In order to reset this cache, we should request pims.vehicle.steps using the parameter resetSteps == true.

In case of error 2317 or 2312 when using pims.authentication.otp - withPIN, you should use "resetStep": true in the query. This action will refresh the cache and remove these errors.