比特币连接
该项目包括连接到闪电钱包和启用的网络组件 网络LN. 网站只需与WebLN接口即可与多个钱包连接,就像Alby扩展. 然而,不需要安装扩展-Bitcoin Connection由网站提供. 用户可以同时从桌面和移动设备连接,使用他们最喜欢的浏览器. PWAs (美国) 只是工作时. Bitcoin Connect的组件与纯HTML和所有的Javascript库或框架相配合,如React,Angular,Vue,Solid.js等.
Bitcoin Connect也支持良好的发票付款UI, 接受单行码的付款.
QQ Bitcoin Connect于2023年12月17日赢得了"BOLT FUN Legends of Lightning vol.2"黑客赛事.
比特币连通公司有些钱可以买礼物 如果您想提供新功能或向受欢迎的网络应用程序添加比特币连接, 请联系 你好@ getalby.com。 。 。 .
试试看
移徙指南
有多个分解变化 页:1. 见我们的移徙指南 这里单击 这里 为v2.
QQ 快速启动
这个软件包目前位于阿尔法. 它有惊人的特性, 但它正在使用 协议的新特性 比如WebLN和NWC 还没有定稿, 并且可能 打破更改或错误.
反应软件包
npm install @getalby/bitcoin-connect-react 或者说 yarn add @getalby/bitcoin-connect-react
Web 组件软件包
npm install @getalby/bitcoin-connect 或者说 yarn add @getalby/bitcoin-connect
HTML (CDN) (中文(简体) )
您可以在没有任何构建工具的情况下使用 Bitcoin 连接 :
<script type="module">
import {launchModal} from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.2'; // jsdelivr.net, skypack.dev also work
// use Bitcoin connect API normally...
launchModal();
// or if you just want access to the web components:
import 'https://esm.sh/@getalby/bitcoin-connect@^3.12.2';
</script>
<!-- Bitcoin Connect components are now available -->
<bc-button></bc-button>
使用量
纯JS
import {
init,
launchModal,
launchPaymentModal,
requestProvider,
} from '@getalby/bitcoin-connect';
// Initialize Bitcoin Connect
init({
appName: 'My Lightning App', // your app name
});
// launch modal programmatically
await launchModal();
// launch modal to receive a payment
await launchPaymentModal({
invoice: 'lnbc...',
onPaid: ({preimage}) => alert('Paid: ' + preimage), // NOTE: only fired if paid with WebLN - see full api documentation below
});
// or request a WebLN provider to use the full WebLN API
const weblnProvider = await requestProvider();
const {preimage} = await weblnProvider.sendPayment('lnbc...');
继续往下走 整个比特币连接API.
反应
import {Button, PayButton, init, launchModal, launchPaymentModal, closeModal, requestProvider, Connect, SendPayment} from '@getalby/bitcoin-connect-react';
// Initialize Bitcoin Connect
init({
appName: "My Lightning App", // your app name
})
// render the Bitcoin Connect button
<Button onConnect={(provider) => {
const {preimage} = await provider.sendPayment("lnbc...");
}}/>
// render a "Pay Now" button
// invoice can be unset initially - using the onClick function is a good time to fetch the invoice
// set the `payment` prop to override the payment status if a payment was made externally
<PayButton invoice={invoice} onClick={() => {
invoice = fetchInvoice();
setInvoice(invoice)
}} onPaid={(response) => alert("Paid! " + response.preimage)} payment={{preimage: 'my-preimage'}}/>
// render the connect flow on its own without the modal
<Connect/>
// render the send payment flow on its own without the modal (for E-Commerce flows)
// set the `payment` prop to override the payment status if a payment was made externally
<Payment invoice="lnbc..." onPaid={(response) => alert("Paid! " + response.preimage)} payment={{preimage: 'my-preimage'}}/>
// request a provider
<button onClick={() => {
// if no WebLN provider exists, it will launch the modal
const weblnProvider = await requestProvider();
const { preimage } = await weblnProvider.sendPayment("lnbc...")
}}>
Request WebLN provider
</button>
// open modal programmatically to connect a wallet
<button onClick={() => launchModal()}>
Programmatically launch modal
</button>
// open modal programmatically to pay an invoice (for one-off payments)
<button onClick={() => launchPaymentModal({invoice: "lnbc...", onPaid: ({preimage}) => alert("Paid: " + preimage)})}>
Programmatically launch payment modal
</button>
// close modal programmatically
closeModal();
下一个联合战略/安全部门改革
确保只导入和制取组件 客户端。可以通过使用下个/动力学与 ssr: false (并在使用下JS应用程序路由器时添加"使用客户端"指令),或者动态导入等.
"use client"
import dynamic from 'next/dynamic';
const Button = dynamic(
() => import('@getalby/bitcoin-connect-react').then((mod) => mod.Button),
{
ssr: false,
}
);
// Render the Button normally
<Button />
// or to use the API:
<button
onClick={async () => {
const launchModal = await import('@getalby/bitcoin-connect-react').then(
(mod) => mod.launchModal
);
launchModal();
}}
>
Launch modal
</button>
// to set the global webln object:
useEffect(() => {
// init bitcoin connect to provide webln
const {onConnected} = await import('@getalby/bitcoin-connect-react').then(
(mod) => mod.onConnected
);
const unsub = onConnected((provider) => {
window.webln = provider;
});
return () => {
unsub();
};
}, []);
见 下一个 JS 财务报告和审定财务报表 下一个 JS 遗产 完整示例的演示.
其他框架
QQ 核心 Bitcoin Connect 包在所有框架上工作,因为它由网络组件提供动力. 然而,包装可以简化比特币连接的使用.
用另一个流行的框架? 请让我们知道,或觉得自由 创建公关为包装。 执行实例见“反应包”.
纯 HTML
构成部分
比特币连接(Bitcoin Connect)为允许用户连接所期望的闪电钱包而暴露出以下的网络组件:
<bc-button/>- 点击启动比特币连接模式- 参数 :
title- (可选)更改按钮的标题
- 参数 :
<bc-pay-button/>- 点击启动比特币连接支付模式- 参数 :
invoice- BOLT11发票 只要开出发票 Modal 才会打开payment-methods(可选)"全""外""内"title- (可选)更改按钮的标题preimage- (可选) 如果您收到外部付款, 设置此选项
- 活动 :
click- 点击按钮时开火。 您可以在此装入一张发票并按下按钮setAttribute('invoice', 'lnbc...')然后自动启动模式bc:onpaid- 火灾事件,WebLN付款反应event.detail(内装)preimage(中文(简体) )
- 参数 :
<bc-connect/>- 无模式地渲染连接钱包<bc-payment/>- 无模式地提出付款请求- 参数 :
invoice- BOLT11发票payment-methods(可选)"全""外""内"paid- 说吧 实验 设定为真实,以标记外部付款(将改为preimage页:1
- 活动 :
bc:onpaid- 火灾事件,WebLN付款反应event.detail(内装)preimage(中文(简体) )
- 参数 :
比特币连接 API
初始化比特币连接
import {init} from '@getalby/bitcoin-connect-react';
// Initialize Bitcoin Connect
init({
appName: 'My Lightning App', // your app name
// filters: ["nwc"],
// showBalance: true,
// persistConnection: true, // if false, connection will not be saved to local storage
// providerConfig: {
// nwc: {
// authorizationUrlOptions: {
// requestMethods: ['get_balance', 'make_invoice', 'lookup_invoice'],
// },
// },
// }
});
appName- 请求访问钱包的应用程序名称。 目前用于NWC连接(例如Alby Hub)filters- 过滤要显示的连接器类型。 示例:"nwc"(只显示NWC连接器).showBalance- 如果错误, 请不要要求连接的钱包余额autoConnect- 如果错误,在页面加载时防止自动连接到用户的NWC钱包. NWC 连接 URL 作为散列传递nwc参数(URL编码). 示例https://myapp.com/#/?nwc=nostr%2Bwalletconnect%3A%2F%2F...providerConfig- 说吧 实验: 添加提供商专用配置(针对NWC,LNC,LNbits等). 目前仅nwc.authorizationUrlOptions被支持.NWCAuthorizationUrlOptions可见于 阿尔比 JS SDK。 。 。 .
请求提供者
有了一行代码,你就可以确保你有一个WebLN供应商,并准备使用. 如果没有,将启动比特币连接模式。 应当要求用户进行互动,以避免向用户意外显示模式.
import {requestProvider} from '@getalby/bitcoin-connect';
const provider = await requestProvider();
await provider.sendPayment('lnbc...');
程序启动模式
然后,可通过以下方式推出该模式:
import {launchModal} from '@getalby/bitcoin-connect';
launchModal(); // A `<bc-modal/>` element will be injected into the DOM
按程序启动收款模式
要收到付款,可按程序以下列方式打开:
import {launchPaymentModal} from '@getalby/bitcoin-connect';
const {setPaid} = launchPaymentModal({
invoice: 'lnbc...',
//paymentMethods: "all" // "all" | "external" | "internal"
onPaid: (response) => {
clearInterval(checkPaymentInterval);
alert('Received payment! ' + response.preimage);
},
onCancelled: () => {
clearInterval(checkPaymentInterval);
alert('Payment cancelled');
},
});
// below is an example of LNURL-verify from https://github.com/getAlby/js-lightning-tools
// you can write your own polling function to check if your invoice has been paid
// and then call the `setPaid` function.
const checkPaymentInterval = setInterval(async () => {
// Make sure your verifyPayment function ONLY verifies the payment.
// If there are any side effects they will only happen when the payment is made externally.
const paid = await invoice.verifyPayment();
if (paid && invoice.preimage) {
setPaid({
preimage: invoice.preimage,
});
}
}, 1000);
注:对于外部支付的P2P付款,Bitcoin Connect无法知道何时付款.
launchPaymentModal更适合简化电子商业用例,您可以亲自检查发票.
程序上关闭模式
import {closeModal} from '@getalby/bitcoin-connect';
closeModal();
连接到用户钱包
import {connect} from '@getalby/bitcoin-connect';
connect({
connectorName: 'NWC',
connectorType: 'nwc.generic',
nwcUrl: 'nostr+walletconnect://...',
});
连接到用户的 NWC 钱包
import {connectNWC} from '@getalby/bitcoin-connect';
connectNWC('nostr+walletconnect://...');
从钱包断开连接
import {disconnect} from '@getalby/bitcoin-connect';
disconnect();
获取连接符配置
返回当前连接连接器的已保存配置( 如果已连接)
import {getConnectorConfig} from '@getalby/bitcoin-connect';
const connectorConfig = getConnectorConfig();
if (connectorConfig) {
// can now access e.g. connectorConfig.connectorName
}
刷新余额
程序上为所有人启动平衡刷新 <bc-balance> 组件。 用于支付或收到资金后更新显示的余额.
import {refreshBalance} from '@getalby/bitcoin-connect';
refreshBalance();
活动
已连接
当提供WebLN供应商时,这一事件就会起火.
- 当用户第一次连接时
- 用户先前已连接时在页面上重新加载
import {onConnected} from '@getalby/bitcoin-connect';
const unsub = onConnected(async (provider) => {
const {preimage} = await provider.sendPayment('lnbc...');
});
unsub();
连接
当一个WebLN提供商在初始化时,这个事件会起火.
- 当用户第一次连接时
- 用户先前已连接时在页面上重新加载
import {onConnecting} from '@getalby/bitcoin-connect';
const unsub = onConnecting(async () => {
// do something...
});
unsub();
已断开
当用户手动断开比特币连接时,此事件会起火.
import {onDisconnected} from '@getalby/bitcoin-connect';
const unsub = onDisconnected(async () => {
// do something...
});
unsub();
已打开
此事件会在比特币连接模式打开时起火.
import {onModalOpened} from '@getalby/bitcoin-connect';
const unsub = onModalOpened(async () => {
// do something...
});
unsub();
在 Modal Closed 上关闭
此事件在比特币连接模式关闭时会起火.
import {onModalClosed} from '@getalby/bitcoin-connect';
const unsub = onModalClosed(async () => {
// do something...
});
unsub();
WebLN 全球对象
警告:webln 默认不再被注入到窗口对象中. 如果你需要这个,你还必须通过断开来清除它。 比特币连接不拥有
window.webln一旦你指定了它,所以一个断开的钱包仍然可以通过被保存的全局到达,直到被移除为止. 对onConnected与onDisconnected数字 :
import {onConnected, onDisconnected} from '@getalby/bitcoin-connect';
onConnected((provider) => {
window.webln = provider;
});
onDisconnected(() => {
delete window.webln;
});
没有 onDisconnected 清理,你的应用程序还可以打电话 window.webln.sendPayment() 在用户点击断开连接后.
很快会有更多方法 你需要什么吗? 告诉我们!
样式
这些变量必须设置在根上或包装任何比特币连接组件的容器元素上.
html {
--bc-color-brand: #196ce7;
--bc-color-brand-dark: #3994ff; /* use a different brand color in dark mode */
--bc-brand-mix: 100%; /* how much to mix the brand color with default foreground color */
--bc-color-brand-button-text: #ffffff; /* override text color for primary button. Normally this is based on the luminance of the brand color */
--bc-color-brand-button-text-dark: #ffffff; /* override text color for primary button in dark mode. Normally this is based on the luminance of the brand color in dark mode */
}
使用近白或黑色的品牌颜色? 或设置下调
bc-brand-mix或确保使用非白色的bc-color-brand并关闭为bc-color-brand-dark以避免与模式背景颜色相冲突.
字体
默认Bitcoin Connect不会使用自定义字体来减少脚印和隐私,但可以通过提供CSS来使用自定义字体 Inter (sans serif) 和 (英语) Roboto Mono (莫诺空间)家庭。 例如,在您的 HTML 标题中:
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
rel="stylesheet"
/>
<link
href="https://fonts.googleapis.com/css2?family=Roboto Mono:wght@400;500;600;700&display=swap"
rel="stylesheet"
/>
黑暗模式
自动( 建议)
比特币连接使用 prefers-color-scheme 以自动检测光/暗模式.
手动
如果您的站点使用手动主题切换器, 您可以通过这些步骤强制一个主题 :
参见示例 这里
- 设定
globalThis.bcDarkMode = "class"在此之前 任何比特币连接组件都会被渲染 "dark"必须作为类名添加到文档中才能启用暗模式(例如).<html class="dark">或者说document.documentElement.classList.add('dark')否则将强制使用光模式.
接触基本供应商(NWC、LNC等)
说明: WebLN 类型 类型定义需要.
import { WebLNProviders, requestProvider } from "@getalby/bitcoin-connect";
const provider = await requestProvider();
if (provider instanceof WebLNProviders.NostrWebLNProvider) {
provider.client.nostrWalletConnectUrl;
}
if (provider instanceof WebLNProviders.LNCWebLNProvider) {
provider.lnc.lnd.lightning.listInvoices(...);
}
if (provider instanceof WebLNProviders.LnbitsWebLNProvider) {
provider.requestLnbits('GET', '/api/v1/wallet');
}
演示文稿
纯 HTML 演示
见 纯 HTML
更完整的例子是: dev/vite/index.html 页面存档备份,存于互联网档案馆 可以通过遵循以下开发指令来操作.
反应演示
见 反应
示例重现
NextJS (App 路由器)
见 下一个 JS
下个JS 后遗症( 文件目录)
更多演示
打开 演示
发展
安装
运行 yarn install && (cd dev/vite && yarn install)
运行虚拟
运行 yarn dev
其他 dev 选项
打开 备忘
生产建设
yarn build
测试
yarn test
需要帮忙吗?
我们乐于提供帮助,请与我们联系或制造问题.
- 推特: @getAlby
- 电报组
- 支持在getalby.com
- 比特币. 设计 Discord社区(在#alby频道找到我们)
- 读取 Alby 开发者指南 要更好地了解 Alby 软件包和 API 如何用来为您的应用程序提供动力.
财务问题
怎么会这样?
比特币连接(Bitcoin Connect)为用户提供多个选项来连接到闪电钱包,每个选项都与WebLN兼容. 任何已经存在的WebLN供应商(如Alby这样的已安装的WebLN扩展)都会被发现和提供,以及通过NWC等协议建立新的WebLN供应商的选项. 无论您选择哪一个选项, WebLN 提供商将会可供网站与您的闪电钱包交互使用. 类似于Alby扩展,新选项(称为Connectors)可以很容易地被添加,因为它们都遵循一个共同的,简单的接口. 只要有办法通过Javascript连接到闪电钱包,就可以在Bitcoin Connect中为它创建连接器. 我们欢迎为新的连接器提供的一切捐助!
这是否适用于移动浏览器和移动PWA,还是没有WebLN扩展的桌面浏览器?
没错! 这是主要的好处.
它是否与桌面扩展功能相通 ?
对 它会使用桌面扩展作为默认连接符, 如果它存在的话.
我可以把它连接到我的手机钱包吗?
这取决于。 连接到您的闪电节点 / 钱包需要同步, 这样您就可以在移动网站或PWAs上使用 Bitcoin Connect .
一个用户能连接任何闪电钱包吗 ?
它只对模式中显示的连接器有效. 其中一些连接器(如Alby浏览器扩展)允许自己连接多个钱包. 随意贡献来添加一个新的连接器.
如果用户离开页面或关闭浏览器,它是否"记得"?
对 您的连接已保存到本地Storage
安全吗?
在您决定连接钱包的网站中, 您应该有一定的信任度, 并且确保不会出现恶意的第三方脚本来读取钱包连接配置, 无论是从内存还是存储中。 我们强烈建议添加 CSP规则 进入您的网站并跟随 最佳做法 来预防XSS.
推荐具有预算控制或确认对话框的连接器( Alby extension 或 NWC), 这样您就可以完全控制您的连接 .
为了把这个添加到网站,我需要做什么?
- 添加“ 连接钱包” 按钮
- 等待连接事件( 使用窗口. add EventListener) , 然后请求用窗口支付发票 。 网络ln
支持什么连接器 ?
如果用户用另一个钱包支付, 为什么模式会保持开放 ?
比特币连接无法检测外部支付. 由你的应用软件来检测付款,然后通过程序关闭模式 closeModal 函数.
为什么是窗户。 连接后未设置 ?
全球 window.webln 如果有多个提供者,对象可以被推翻,从而导致出乎意料的行为。 我们建议使用 requestProvider 函数以获取 WebLN 提供者,而不是依赖全局窗口对象.
为什么Bitcoin Connect在一些页面上不起作用?
Bitcoin Connection 必须在根元件上或每个需要webln的元件上导入,以确保webln可用. 如果您仅在设置页面中导入按钮, 您仍需要导入您想要进行闪电付款的库 。 我们建议使用 requestProvider 函数.
已知问题
- NWC连接器在不安全的情况下不工作于iOS,因为窗口. 密码. subtle 不可用 。 如果在您的电话中测试, 请运行 https 服务器或使用 https 隧道 .
🔥 立特
这个项目由Lit提供动力.
见 开始吧 在Lit网站获取更多信息.