The Plugchoice SDK is in beta. Until version 1.0, a minor version may change the SDK or the SDK API. Pin the SDK version in your app and the
Plugchoice-Version header on your server.Before you start
- Test credentials for the SDK API: a client ID and secret. Email support@plugchoice.com to get them; see Test and live.
- The SDK in your app: follow Installation and the configuration on your platform’s page (iOS, Android, React Native).
- A charger to add: an Alfen, Charge Amps, Easee, Enovates, go-e, Peblar, Ratio, SolarEdge, Teltonika, Volt Time, Wallbox, Webasto or Zaptec charger, or any other OCPP 1.6 charger. Test mode works with real chargers; see Test and live.
- A phone: Wi-Fi hotspots, the local network and Bluetooth don’t work in a simulator.
1. Get an access token
Your server exchanges its client ID and secret for an access token, which lasts an hour:plugchoice.ts
2. Write your endpoint
Your app asks your server for a client secret whenever Link needs one. It sends the action Link opens for, so your server can scope the client session to that action alone: the charger to work on, or where to add one.server.ts
external_user_idis your own id for the signed-in user. The first client session for it creates that user at Plugchoice.- The charger goes to your user’s own Plugchoice account, and you get access to it. That’s the default; Plugchoice can set your integration up so the chargers go to your team instead, and then an
addwith asiteIdscopes to{ sites: [siteId] }. See Client sessions and scopes. - The SDK API checks every id in the scope against that user: a charger that isn’t theirs, or that they didn’t give you access to, is
404 not-found. - The client secret works for an hour. Link asks for a new one by itself when it runs out.
3. Give the SDK your endpoint
Create one SDK instance when your app starts. ItsfetchClientSecret calls your endpoint with the action and returns the client secret.
- iOS
- Android
- React Native
backend.plugchoiceClientSecret stands for your own code: it posts the action’s name, chargerId and siteId to your endpoint, with your user’s session, and returns clientSecret. If it fails or takes longer than 30 seconds, Link shows an error screen with Try again.
4. Open Link
Open Link with theadd action, for example from an Add charger button:
- iOS
- Android
- React Native
5. Handle the result
Link closes with a result. On success, send itssessionId to your server.
- iOS
- Android
- React Native
devices Link finished, { type: "charger", id }. Use it to update your screen, but let your server decide what’s true.
6. Confirm on your server
Read the link session with Get a link session, check it belongs to the signed-in user, and store its chargers:server.ts
GET /sdk/v1/chargers?external_user_id=user-123, and their charging sessions with GET /sdk/v1/transactions?external_user_id=user-123 when they let you read them (sessions:read). See Link sessions for what each status means, and List transactions.
7. Offer the next actions
Once a charger is added, your app can open Link for it again: to set it up (setup), or to bring it back online or change its network (reconnect). Show each only where it works: the charger’s capabilities from Get a charger say what Plugchoice can do for it, and the SDK’s transports() says what this phone can do. See Devices and capabilities.
- iOS
- Android
- React Native
8. Go live
When your integration works in test mode, email support@plugchoice.com to go live. Plugchoice switches your integration to live: its client secrets then start withcs_live_, and nothing in your code changes. Check your profile and accent colour under Settings > SDK first, for the consent screen; see Consent and branding.