Skip to main content
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.
This guide adds a charger end to end, in test mode. You write one endpoint on your server, open Link from your app, and confirm the outcome 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:
Reuse the token until it expires. In Node:
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_id is 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 add with a siteId scopes 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.
Do you already know your user’s address? Send scope: { location: { reference, address, timezone } } instead of new_site, as the address of the charger’s site. When the charger goes to your user’s own account, it’s a hint for the site they pick. See Client sessions and scopes.
The same request with curl:

3. Give the SDK your endpoint

Create one SDK instance when your app starts. Its fetchClientSecret calls your endpoint with the action and returns the client secret.
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. Open Link with the add action, for example from an Add charger button:
Your user agrees to share their charger with you, picks the brand and model, and Link sets the charger up. Then your user signs in to their Plugchoice account, or creates one, with a code by email, Google or Apple, and picks the site it goes to.

5. Handle the result

Link closes with a result. On success, send its sessionId to your server.
The result also lists the 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
You can list all of a user’s chargers at any time with 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.
Your endpoint from step 2 already scopes these to the one charger.

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 with cs_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.