> ## Documentation Index
> Fetch the complete documentation index at: https://developer.plugchoice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Link works

> The few ideas behind the Plugchoice SDK, in plain words.

export const Screen = ({name, alt, caption, wide = false}) => {
  const style = wide ? {
    width: '100%'
  } : {
    width: '280px',
    maxWidth: '100%'
  };
  return <figure style={{
    margin: '1.5rem 0',
    textAlign: 'center'
  }}>
      <img className="block dark:hidden" src={`/images/sdk/${name}-light.webp`} alt={alt} style={{
    ...style,
    margin: '0 auto',
    borderRadius: '12px',
    border: '1px solid rgba(128, 128, 128, 0.25)'
  }} />
      <img className="hidden dark:block" src={`/images/sdk/${name}-dark.webp`} alt={alt} style={{
    ...style,
    margin: '0 auto',
    borderRadius: '12px',
    border: '1px solid rgba(128, 128, 128, 0.25)'
  }} />
      {caption ? <figcaption style={{
    marginTop: '0.5rem',
    fontSize: '0.875rem',
    opacity: 0.7
  }}>{caption}</figcaption> : null}
    </figure>;
};

Link is a set of screens that guides your user through connecting their charger. Three parties work together to show it: your app, your server and Plugchoice. This page walks through one charger being added, and the ideas you meet along the way.

## One charger, start to finish

<Steps>
  <Step title="Your user taps Connect charger">
    Your app opens Link for an **action**: what your user wants to do. Here that's `add`, to add a charger.
  </Step>

  <Step title="The SDK asks your server for a client secret">
    The SDK calls your app's callback, which asks your server. Your server asks Plugchoice for a **client session** for this user, and passes its secret back. Your own API credentials never leave your server.
  </Step>

  <Step title="Your user agrees to share their charger">
    The first time, Link asks your user whether you may see and control their chargers. This happens once per user.

    <Screen name="consent" alt="The consent screen: Connect your charger to Acme Energy" />
  </Step>

  <Step title="Link sets up the charger">
    Your user picks their charger's brand and follows the steps for it. Link does the technical work, such as joining the charger's own Wi-Fi or talking to it over Bluetooth, and shows its progress as a checklist.

    <Screen name="run-list" alt="Setting up your charger: a checklist with the steps done so far" />
  </Step>

  <Step title="Link closes and tells your app">
    Your app gets the result: whether it worked, and which chargers were added. Your server confirms it with Plugchoice, and the charger is ready to use in your app.
  </Step>
</Steps>

## The ideas behind it

<AccordionGroup>
  <Accordion title="Actions: what your user wants to do" icon="hand-pointer" defaultOpen>
    Your app opens Link for one action at a time:

    | Action | What your user does |
    | - | - |
    | `add` | Adds a new charger |
    | `network` | Moves a charger to another Wi-Fi network |
    | `setup` | Tells Plugchoice how the charger is wired, such as its maximum current |
    | `reconnect` | Brings a charger that lost its connection back online |

    Everything except `add` is about one charger, so you pass its id. [Actions](/sdk/concepts/actions)
  </Accordion>

  <Accordion title="Client sessions: a short-lived pass for one user" icon="key">
    A client session is like a visitor's pass. Your server creates one for the signed-in user, and it says which chargers and sites that user may touch: its **scope**. It's valid for an hour.

    Its **client secret** is what your app hands to the SDK. Because the scope is in the client session, a secret can't reach the rest of your chargers, even if someone copies it. [Client sessions](/sdk/concepts/client-sessions)
  </Accordion>

  <Accordion title="Link sessions: one time through Link" icon="list-check">
    Each time your user goes through Link, Plugchoice keeps a record of it: a link session. It says how it ended (finished, left or failed) and which chargers it finished.

    Your app gets the link session's id when Link closes and passes it to your server. Your server reads the link session from Plugchoice before it relies on the result, and checks it's for the signed-in user. If your app never reports back, for example because it was closed, the link session is still there. [Link sessions](/sdk/concepts/link-sessions)
  </Accordion>

  <Accordion title="Capabilities: which buttons to show" icon="toggle-on">
    Not every charger supports every action. Each charger in the SDK API lists its capabilities: whether Link can change its Wi-Fi, set it up or reconnect it, and what the phone needs for it, such as Bluetooth.

    Show a button only when the charger supports the action and the phone can do it. [Capabilities](/sdk/concepts/capabilities)
  </Accordion>

  <Accordion title="Test and live: try it without risk" icon="flask">
    You get test credentials first. Test mode works with real chargers, so you can try everything with your own. When your integration works, Plugchoice switches it to live. [Test and live](/sdk/concepts/test-and-live)
  </Accordion>
</AccordionGroup>

## Who does what

| | Does |
| - | - |
| **Your app** | Shows the button, opens Link, and handles the result |
| **Your server** | Creates client sessions and confirms the result. It keeps your API credentials. |
| **The SDK** | Shows Link full screen, and gives it what only a phone can do: Wi-Fi, the local network, Bluetooth and the camera |
| **Plugchoice** | Runs Link's screens, keeps them up to date for new brands, and connects the charger |

## Next

<Columns cols={2}>
  <Card title="Get started" icon="rocket" href="/sdk/get-started">
    Build the three pieces and add a charger, end to end.
  </Card>

  <Card title="Installation" icon="download" href="/sdk/install">
    Add the SDK to your iOS, Android or React Native app.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.