Merge pull request #203 from Apillon/staging

Staging

Author: dimitrov-d

build/12-embedded-wallets-integration.md

@@ -22,34 +22,50 @@ A Vite plugin is required for running and building Vite apps with Embedded Walle
 npm install -D vite-plugin-node-polyfills
 ```
 
+HTTPS needs to be configured even for localhost, so that authentication can work accross multiple domains.
+This can be achieved with vite-plugin-mkcert Vite plugin.
+
+```sh
+npm i vite-plugin-mkcert -D
+```
+
 ```ts
 // vite.config.ts
 import { defineConfig } from "vite";
 import { nodePolyfills } from "vite-plugin-node-polyfills";
+import mkcert from "vite-plugin-mkcert";
 
 export default defineConfig({
-  plugins: [nodePolyfills() /* ... */],
+  plugins: [nodePolyfills(), mkcert() /* ... */],
 });
 ```
 
 ### Next.js
 
-To use the Embedded wallet UI, your Next app has to be in `app router` mode. When in `pages routing` mode, global CSS file imports throw an error. [Github Discussion](https://github.com/vercel/next.js/discussions/27953).
+To use the Embedded wallet UI, your Next app has to be in `app router` mode. When in `pages routing` mode, global CSS file imports throw an error. [Github Discussion](https://github.com/vercel/next.js/discussions/27953)
+
+Embedded wallet relies on browser APIs and it doesn't make sense to run it server-side.
+To avoid errors, the component including `<WalletWidget />` should be marked with `'use client';`
+
+HTTPS needs to be configured even for localhost, so that authentication can work accross multiple domains.
+In Next.js you can do this by adding `--experimental-https` to dev command.
+
+```sh
+next dev --experimental-https
+```
 
 ### Nuxt
 
 When using Vite as the build tool, a Vite plugin is required for running and building Nuxt apps with Embedded Wallet. This plugin enables Node API in the browser (eg. buffer, crypto).
 
-::: warning
-The Embedded wallet integration includes a style (CSS) file imported through JavaScript.
-Nuxt fails to resolve this import by default.
-To avoid errors, the Embedded wallet dependency needs to be added to the [build.transpile](https://nuxt.com/docs/api/nuxt-config#transpile) setting.
-:::
-
 ```sh
 npm i -D vite-plugin-node-polyfills
 ```
 
+The Embedded wallet integration includes a style (CSS) file imported through JavaScript.
+Nuxt fails to resolve this import by default.
+To avoid errors, the Embedded wallet dependency needs to be added to the [build.transpile](https://nuxt.com/docs/api/nuxt-config#transpile) setting.
+
 ```ts
 // nuxt.config.ts
 import { nodePolyfills } from "vite-plugin-node-polyfills";
@@ -59,12 +75,47 @@ export default defineNuxtConfig({
     plugins: [nodePolyfills() /* ... */],
   },
   build: {
-    transpile: ["@apillon/wallet-vue"],
+    transpile: [/@apillon[\\/]wallet-vue/],
   },
   /* ... */
 });
 ```
 
+Embedded wallet relies on browser APIs and it doesn't make sense to run it server-side.
+To avoid errors, wrap the wallet with `<ClientOnly />`.
+
+```vue
+<template>
+  <ClientOnly>
+    <WalletWidget clientId="..." />
+  </ClientOnly>
+</template>
+```
+
+HTTPS needs to be configured even for localhost, so that authentication can work accross multiple domains.
+In Nuxt.js you can do this by:
+
+- add `--https` to dev command
+
+- install [mkcert](https://github.com/FiloSottile/mkcert)
+
+- make a localhost certificate in project folder: `mkcert localhost`
+
+- edit `nuxt.config.ts` to use the certificate for the dev server
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  // ...
+  devServer: {
+    https: {
+      key: "localhost-key.pem",
+      cert: "localhost.pem",
+    },
+  },
+});
+```
+
 ## Installation
 
   <CodeGroup>
@@ -117,7 +168,7 @@ import { WalletWidget } from "@apillon/wallet-react";
     },
     /* ... */
   ]}
-/>
+/>;
 ```
 
   </CodeGroupItem>
@@ -158,7 +209,7 @@ EmbeddedWalletUI("#wallet", {
       explorerUrl: "https://moonbase.moonscan.io",
     },
     /* ... */
-  ]
+  ],
 });
 ```
 
@@ -167,14 +218,14 @@ EmbeddedWalletUI("#wallet", {
 
 ### Parameters
 
-| Field                        | Type        | Required | Description                                                                                                                                        |
-| ---------------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| clientId                     | `string`    | Yes      | UUID of the integration that you obtain when creating it on the [Apillon embedded wallet dashboard](https://app.apillon.io/dashboard/service/embedded-wallet).            |
-| defaultNetworkId  | `number`    | No       | Chain ID set as default when opening wallet.                                                                                                       |
-| networks                     | `Network[]` | No       | Array of network specifications                                                                                                                    |
-| broadcastAfterSign           | `boolean`   | No       | Automatically broadcast with SDK after confirming a transaction.                                                                                   |
-| disableDefaultActivatorStyle | `boolean`   | No       | Remove styles from "open wallet" button                                                                                                            |
-| authFormPlaceholder          | `string`    | No       | Placeholder displayed in input for username/email                                                                                                  |
+| Field                        | Type        | Required | Description                                                                                                                                                    |
+| ---------------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| clientId                     | `string`    | Yes      | UUID of the integration that you obtain when creating it on the [Apillon embedded wallet dashboard](https://app.apillon.io/dashboard/service/embedded-wallet). |
+| defaultNetworkId             | `number`    | No       | Chain ID set as default when opening wallet.                                                                                                                   |
+| networks                     | `Network[]` | No       | Array of network specifications                                                                                                                                |
+| broadcastAfterSign           | `boolean`   | No       | Automatically broadcast with SDK after confirming a transaction.                                                                                               |
+| disableDefaultActivatorStyle | `boolean`   | No       | Remove styles from "open wallet" button                                                                                                                        |
+| authFormPlaceholder          | `string`    | No       | Placeholder displayed in input for username/email                                                                                                              |
 
 #### Network Object
 
@@ -185,13 +236,23 @@ To find the information for your desired network, visit [chainlist.org](https://
 :::
 
 | Field       | Type     | Description                             |
-| ----------- | -------- | ----------------------------------------|
+| ----------- | -------- | --------------------------------------- |
 | name        | `string` | The name of the network                 |
 | id          | `number` | The unique Chain ID of the network      |
 | rpcUrl      | `string` | The URL to the network's RPC server     |
 | explorerUrl | `string` | The URL to the network's block explorer |
 
+### Button style
 
+You can style the activator button by targeting `#oaw-wallet-widget-btn` css ID.
+Use `disableDefaultActivatorStyle` option to make the button unstyled.
+
+You can also hide the activator button (`display: none;`) and open the wallet programmatically, eg. from a menu item or your own button.
+
+```ts
+// const wallet = getEmbeddedWallet();
+wallet.events.emit("open", true);
+```
 
 ## Use wallet
 
@@ -204,7 +265,7 @@ To access wallet signer and wallet information we provide core imports (hooks/co
 import { useAccount, useContract, useWallet } from "@apillon/wallet-react";
 
 export default function Component() {
-  const { username, address, getBalance } = useAccount();
+  const { info, getBalance } = useAccount();
   const { wallet, signMessage, sendTransaction } = useWallet();
 
   const { read, write } = useContract({
@@ -222,8 +283,14 @@ export default function Component() {
     return wallet.userExists(username);
   };
 
+  // get account info
+  const getAccountInfo() = async () => {
+    console.log(info.address);
+    console.log(await getBalance());
+  }
+
   // sign a message
-  const onSignMessage = await (msg: string) => {
+  const onSignMessage = async (msg: string) => {
     await signMessage(msg);
   };
 
@@ -266,6 +333,12 @@ function getWalletUserExists(username: string) {
   return wallet.value.userExists(username);
 }
 
+// get account info
+async function getAccountInfo() {
+  console.log(info.address);
+  console.log(await getBalance());
+}
+
 // sign a message
 async function onSignMessage(msg: string) {
   await signMessage(msg);