README

Cipherwallet 是一款数字钱包移动应用程序。用户可以存储个人数据，如姓名、地址、电话号码或信用卡。显示从 cipherwallet API 获得的特殊定制二维码的网站可以轻松且安全地从移动应用程序中收集用户数据。更多详细信息，请参阅 cipherwallet 产品官方网站。还提供了一个完全功能性的 演示。

此 SDK 提供了一组可用于将 cipherwallet 集成到您网站中的函数 - 实际上它简化了对 cipherwallet API 的访问。如您所注意到的，我们选择了一个非常基础、非框架、易于理解的实现，而不是提供复杂和学术性的解决方案。我们希望您这些极客们能找到很多改进它的方法。

您大部分时间将花费在以下方面

• 了解信息交换数据流；
• 设置 constants.php 中的常量；
• 在 hooks.php 模块中实现几个非常基本的函数；
• 在您的网页中连接 SDK 调用和返回的结果。我们还有一些示例实现，可以帮助您更快地上手。

TL;DR

• 克隆项目。SDK 文件将位于 /cipherwallet 目录中 - 确保您的网站不提供对该目录中文件的直接访问。
• 将 constants.sample.php 和 hooks.sample.php 文件复制为 constants.php 和 hooks.php。在新文件中进行您需要的设置。您的客户 ID 和秘密 API 密钥可在 cipherwallet [仪表板] 上找到。
• 如果您计划使用 cipherwallet 登录服务，则在您的数据库中创建一个额外的表来存储 cipherwallet 需要的用户属性。（请参阅 db-interface.lib.php 模块的顶部。）
• 在您的网页中添加 <div> 元素，其中应显示二维码。确保页面加载 cipherwallet/cipherwallet.js 中的 JavaScript 代码。
• 使用客户 [仪表板] 编程用户在扫描二维码时在手机上看到的内容，以及要传递给您的 web 应用的参数名称。确保回调脚本 cb-*.php 可从互联网访问，并在 [仪表板] 中提供它们的 URL。
• 在您的网页 JavaScript 代码中，实例化一个 Cipherwallet 对象并实现其回调函数。通常这些函数将用户数据分配到您的网页元素上，或处理错误条件。

详细信息，请继续阅读。

Terraforming

克隆 cipherwallet SDK 项目

git clone https://github.com/drivefast/php-cipherwallet.git

如果您不熟悉 git，克隆将基本上在您的当前文件夹中创建一个名为 php-cipherwallet 的目录，并将所有 SDK 文件复制到那里。

位于 php-cipherwallet/example/ 目录下的文件是一个示例网站。实际的 SDK 文件最终位于 php-cipherwallet/cipherwallet/ 目录中。将 SDK 连接到您的网站的最简单方法是在您的网站根目录中创建一个指向包含 cipherwallet 脚本的目录的符号链接。在 Linux 中，这将是这样：

ln -s /path/to/php-cipherwallet/cipherwallet /your/website/root/cipherwallet 

确保您的网站代码可以执行 SDK 目录中的脚本，但禁止目录和查看/下载操作。

SDK包含两个示例文件：constants.sample.php 和 hooks.sample.php。将这些文件复制，但将它们的名称中的单词sample删除，使它们的名称变为constants.php 和 hooks.php。请确保这些文件的内容对外部世界不可用，因为它们最终会存储敏感信息。请在您的 .htaccess 文件中（如果使用 Apache）仔细屏蔽它们，当它们在 nginx 中直接调用时返回 404 Not Found 错误——您明白这个意思。

constants.php是一个通用常量文件，其中您设置访问 cipherwallet API 的权限、连接到您的数据库和后端系统等。您还会找到描述服务执行的模板。我们将在稍后详细讨论它们。

如果您还没有cipherwallet账户，现在是创建它的好时机。免费评估层具有付费账户的所有功能，我们鼓励您在初始开发阶段使用此层。当您登录cipherwallet网站时，您将直接进入[仪表板]页面。在API设置部分，您可以找到您的客户ID和密钥。将这些两个值复制到constants.php中的CUSTOMER_ID和API_SECRET常量中。此外，在创建实现时，您可能想为DEBUG常量提供一个文件名，而不是FALSE；SDK将在该文件中提供有用的输出。

您的应用程序需要暂时存储从移动应用程序接收的数据，这些数据将通过浏览器显示的网页进行传输。我们提供了可以与 APC、memcached、redis、mongoDB 或纯文本文件后端（显然，APC 和纯文本会话文件不建议用于生产环境）一起工作的库。取消注释定义TMP_DATASTORE常量的行之一，并按需提供连接信息。

检查服务

SDK提供了生成cipherwallet API请求用于二维码、显示它、轮询数据接收状态以及根据轮询返回的数据采取行动的所有工具。有关检查服务如何工作的详细说明，请参阅检查服务文档。

从您的网站上的检查页面开始，请确保为 html 表单中的每个输入字段分配一个ID。在[仪表板]页面中创建服务，表明您将使用PHP SDK，并配置您需要的所有设置和参数。

在您的检查网页的javascript代码中，加载cipherwallet/cipherwallet.js模块

<script src="cipherwallet/cipherwallet.js" type="text/javascript"></script> 

找到一个显示二维码的地方，并为其创建一个<div>容器。实例化一个Cipherwallet对象，并提供初始化变量

• qrContainerID = 我们刚才提到的<div>html容器的id
• detailsURL = 当用户点击二维码或下面的“这是什么”超链接时，用户的浏览器将被重定向到的位置
• onSuccess = 当轮询操作从您的web服务器返回数据集时执行的函数。该函数接收作为参数的数据对象本身。您可以使用此函数将来自移动应用程序的数据写入检查表单的相应字段。
• onFailure = 当轮询操作返回400或500范围内的http状态时执行的函数。该函数接收作为参数的轮询http状态。您可以在我们的演示网站或[仪表板]页面本身查看实现示例。

检查服务不需要连接到您的数据库后端，因此您可以安全地取消注释constants.php中的所有DSN常量的替代定义。

然而，您确实需要在$qr_requests字典变量中添加一个条目。该条目需要与[仪表板]页面中的名称（键）相同，并且本身也需要是一个包含以下元素的字典

• operation = 操作类型，在这种情况下为OP_CHECKOUT
• qr_ttl = （可选）二维码激活的时间长度，单位为秒。对于结账二维码，默认值为300秒（5分钟），最大值为600秒（10分钟）
• display = （可选）在移动应用程序请求数据时，显示在屏幕顶部的文本。此文本将覆盖[仪表板]页面中相应的服务设置。您可以使用一个常量字符串，或者一个返回字符串的函数（例如，一个查找购物车中商品总价值的函数，并返回类似“我们将为您购物车中的3件商品收费27.84美元”的字符串）。在hooks.php中实现此函数是一种良好的做法。
• callback_url = （可选）处理从移动应用程序接收到的数据的URL。它将覆盖[仪表板]页面中相应的服务设置。对于此SDK，URL预期为https://your.website.com/cipherwallet/cb-checkout.php。请注意，如果URL不是https方案，则会自动向用户显示警告消息。
• rq_params = （可选）(未实现)
• confirm = （可选）在移动应用程序中显示的文本，作为数据传输的结果，指示传输成功。您可以提供字符串，或者一个返回字符串的函数（例如，一个检查信用卡类型的函数，并返回“感谢您的付款”或“很抱歉，我们只接受VISA或万事达卡”）。

请确保您的回调URL https://your.website.com/cipherwallet/cb-checkout.php可以从互联网访问。另外，请确保它是一个安全的http（即以https://开头）：信用卡信息是敏感信息，需要在移动应用程序和您的网络应用程序之间以加密形式传输。如果您不使用安全的http，移动应用程序用户将会收到通知。

注册服务

注册过程与结账服务非常相似，但为了注册用户进行cipherwallet登录，还需要做更多的工作。

类似于您为结账服务创建的，请继续在注册网页上提供一个<div>标签，二维码将在其中显示。在您的页面上导入cipherwallet/cipherwallet.js模块，并创建一个包含所有所需参数和函数的Cipherwallet对象实例。在$qr_requests变量中创建一个服务描述符，与在[仪表板]中使用的相同名称（键）。对于此服务，提供与结账服务相同的数据（对于operation键使用OP_SIGNUP）。

接下来是（略微）复杂的部分。如注册服务文档中所述，对于完成的注册，您需要存储用户的cipherwallet登录凭证，以及其他用户数据。我们不是要破坏您的用户表，并要求您添加cipherwallet应用程序使用的字段，而是选择要求您创建一个名为cw_logins的单独表，并与现有的用户表保持一对一的关系。如果您使用几乎任何SQL数据库作为后端，cipherwallet登录表将如下所示

CREATE TABLE cw_logins (
    user_id VARCHAR(...) PRIMARY KEY,  -- or whatever type your unique user ID is
    cw_id VARCHAR(20),
    secret VARCHAR(128),
    reg_tag CHAR(...),                 -- it's an UUID
    hash_method VARCHAR(8),            -- can be md5, sha1, sha256
    created INTEGER
);

《user_id》字段既是您现有用户表的主键，也是外键。请选择合适的数据类型，创建关系，并确保您有一个在删除常规用户表中的对应记录时删除《cw_logins》记录的程序。《reg_tag》字段需要用于移除用户的cipherwallet登录权限：如果您删除cipherwallet用户记录，也应该调用cipherwallet API来使他们的登录能力失效。《hash_method》将采用在创建记录时设置的《H_METHOD》常量的值。

SDK还需要访问您的数据库，以维护《cw_logins》表。我们使用[PDO]来访问数据库，它适用于大多数类型的SQL后端。在《constants.php》中取消注释匹配您数据库类型的《DSN》常量，填写正确的值，并在《DB_USERNAME》和《DB_PASSWORD》常量中提供权限。

还有一件事要做。在成功的场景中，扫描注册QR码的用户将把他们的移动应用中的数据传输到您的网页上的注册表单中，并最终按下“提交”按钮。到那时，我们假设您的Web应用在数据库中创建用户记录，但它也应该在《cw_logins》中创建相应的记录。因此，在提交按钮上执行任何操作的同时，您还应该调用为您的页面创建的《Cipherwallet》对象的《registerForQRLogin()`方法。《registerForQRLogin()`函数接受两个参数 - 您分配给新用户的用户ID，以及一个在cipherwallet注册操作结束时执行的javascript回调函数。如果您感觉更舒服，可以在您的代码中包含（要求）《cipherwallet/cw-signup.php》模块，并自行调用《set_qr_login_data()`函数。该函数的参数是您创建的新用户的用户ID和服务的名称（在[仪表板]中声明，用作容纳QR码的《