Add a device

By the end of this page Alice’s phone joins her identity, and shows her name, her spaces and her contacts.

Background

Each device has its own key. Adding a device is the same handshake as inviting a person, with a device invitation instead of a space invitation: the device already in the identity is the host, and the new device the guest. At the end, the host writes a delegation that makes the new device a member of the identity’s group.

The new device then syncs the identity’s personal space and every space the identity is in, from the other device or through EDGE. Nothing about the identity has to be typed in again.

Steps

1. Share your identity. Identity.share starts a device invitation on the device you have. Add a device on the Devices tab calls this and shows the code.

   src/app/Devices.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity, Invitation } from '@dxos/halo';
   import { useDevices, useHaloServices } from '@dxos/halo-react';
   
   import { Host } from './Invitations.tsx';
   
   /** Your identity's devices, and a way to add another. */
   export const Devices = () => {
     const services = useHaloServices();
     const [adding, setAdding] = useState(false);
   
     /** Starts an invitation for another device of yours, and returns the flow and the code to open there. */
     const handleAdd = () =>
       Effect.gen(function* () {
         const flow = yield* Identity.share({ authMethod: 'shared-secret' });
         const code = yield* Invitation.code(flow);
         return { flow, code };
       }).pipe(Effect.provide(services), Effect.runPromise);
   
   

2. Join from the new device. On the new device, before it has an identity, Identity.join redeems the code. The handshake and its authorization code are the same as for a space, so the welcome screen hands the flow to the same guest panel as Join. Join your other device calls this.

   src/app/Welcome.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity } from '@dxos/halo';
   import { useHaloServices } from '@dxos/halo-react';
   
   import { type Stage, reached } from '../stage.ts';
   import { Guest } from './Invitations.tsx';
   import { Prompt } from './ui.tsx';
   
   /** The device before it has an identity: start one, join one from another device, or recover one. */
   export const Welcome = ({ stage }: { stage: Stage }) => {
     const services = useHaloServices();
     const [mode, setMode] = useState<'new' | 'device' | 'recover'>('new');
     // Focusing the first field on load would scroll the page to the embed.
     const [picked, setPicked] = useState(false);
     const pick = (next: typeof mode) => {
       setPicked(true);
       setMode(next);
     };
   
     /** Creates the identity, with this device as its first member. */
     const handleStart = (name: string) =>
       Identity.create({ displayName: name }).pipe(
         Effect.provide(services),
         Effect.runPromise,
       );
   
     /** Redeems the invitation `code` from your other device, and returns the flow. */
     const handleJoin = (code: string) =>
       Identity.join(code).pipe(Effect.provide(services), Effect.runPromise);
   
   

3. List your devices. useDevices returns the identity’s devices and re-renders when one joins or comes online. It follows Identity.devices. Each device has a key, a kind, whether it is online, and whether it is the device the code runs on. The Devices tab shows them.

   src/app/Devices.tsx

   import { useDevices, useHaloServices } from '@dxos/halo-react';
   
   import { Host } from './Invitations.tsx';
   
   /** Your identity's devices, and a way to add another. */
   export const Devices = () => {
     const services = useHaloServices();
     const [adding, setAdding] = useState(false);
   
     /** Starts an invitation for another device of yours, and returns the flow and the code to open there. */
     const handleAdd = () =>
       Effect.gen(function* () {
         const flow = yield* Identity.share({ authMethod: 'shared-secret' });
         const code = yield* Invitation.code(flow);
         return { flow, code };
       }).pipe(Effect.provide(services), Effect.runPromise);
   
     /** Your devices, re-rendering on each change. */
     const devices = useDevices();
   
   

Try it

Alice’s laptop has her identity, her spaces and her contacts; her phone has nothing.

1. On the laptop, open Devices, press Add a device and copy the code.
2. On the phone, press Join your other device, paste it and press Join.
3. Type the authorization code the laptop shows into the phone and press Send.

The phone now shows Alice’s name, both spaces and both contacts, and each device lists the other.

What you can do now

You can add a device to your identity and list your devices. Next, Recover an identity covers losing all of them.