README

一个简单的 API 包装器，用于集成 TWIPLA 提供的分析作为服务（3AS）API

入门指南

1. 创建 RSA 密钥对（PEM 格式）
2. 将生成的公钥（jwtRS256.key.pub）发送给 TWIPLA 开发团队
3. 安装库
4. 使用 SDK 实例 与 API 交互

创建 RSA 密钥对

1. 创建密钥对：ssh-keygen -t rsa -b 2048 -m PEM -f jwtRS256.key
2. 将公钥转换为 PEM：openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

安装

Composer

通过 Composer 安装

composer require visitor-analytics/3as-sdk

如何使用库

$visa = new VisitorAnalytics([
     'intp' => [
         'id' => {INTP_ID},
         'privateKey' => {INTP_RS256_PRIVATE_KEY}
     ],
     'env' => 'stage'
]);

概念

术语

• INTP（集成合作伙伴）
  集成分析作为服务（3AS）解决方案的公司
• STPs（服务器触点）
  用于衡量特定网站数据使用的信用
• 客户（INTPC 集成合作伙伴客户）
  一个 INTP 用户可以有多个网站
• 网站
  数据将被跟踪的网站。它有一个与具有一定 STPs 限制的包的订阅。此订阅可以升级或降级。当创建网站时，将返回一个必须嵌入网站 HTML 中的跟踪代码片段。
• 包
  包具有价格，包含一定数量的 STPs。它们用于升级/降级网站的订阅。

通用

大多数涉及客户或网站端点支持某种形式的 ID，可以提供并用于所有后续请求。

例如，创建具有网站的新的客户需要 intpCustomerId 和 intpWebsiteId。这些必须由 INTP 提供，目的是使集成更容易，因为无需保存任何外部 ID。然后，当获取有关客户的详细信息时，请求是使用创建时提供的相同的 intpCustomerId 进行的。

示例实现流程

1. 创建具有网站的新的客户
2. 将生成的跟踪代码注入网站 HTML 中
3. 使用 SDK 的 生成 iframe URL 方法创建 URL
4. 向用户显示之前创建的 URL
5. 向用户显示模态窗口以升级其订阅
6. 使用 SDK 显示所有可用包
7. 支付完成后，使用 SDK 升级网站的订阅

可用 API

• 客户
• 客户
• 包
• 包
• 网站
• 网站
• 实用工具

客户 API

集成合作伙伴（INTP）能够获取有关其客户（INTPc）的数据。

注册新的客户

$visa->customers->create([
        'intpCustomerId' => {INTP_CUSTOMER_ID},
        'email' => {INTP_CUSTOMER_EMAIL},
        'website' => [
            'intpWebsiteId' => {INTP_WEBSITE_ID},
            'domain' => {INTP_WEBSITE_DOMAIN_URI},
            'packageId' => {PACKAGE_UUID},
            'billingDate' => {ISO_DATE_STRING} (optional, defaults to current time)
        ]
]);

列出所有可用的客户

$visa->customers->list();

通过 INTP 给定的 ID 获取单个客户

$visa->customers->getByIntpCustomerId({INTP_CUSTOMER_ID});

客户 API

列出属于 INTP 客户的所有网站

$visa->customer({INTP_CUSTOMER_ID})->listWebsites();

删除属于 INTP 的客户

$visa->customer({INTP_CUSTOMER_ID})->delete();

生成访客分析仪表板 iframe URL

这是在使用iframe方法3AS时必须使用的一种基本方法。它为特定客户和网站组合创建一个URL，该URL显示由INTP配置的主题中的TWIPLA仪表板。

$visa->customer({INTP_CUSTOMER_ID})->generateIFrameDashboardUrl({INTP_WEBSITE_ID});

包API

集成合作伙伴（INTP）能够获取有关其包的数据

列出所有可用包

$visa->packages->list();

通过ID获取单个包

$visa->packages->getById({PACKAGE_UUID});

创建一个包

$visa->packages->create([
    'name' => {PACKAGE_NAME},
    'touchpoints' => {TOUCHPOINT_LIMIT},
    'price' => {FLOAT},
    'currency' => {CURRENCY_CODE}, // ex: EUR, USD, RON
    'period' => {PERIOD}, // ex: monthly, yearly
]);

包API

INTP可以更新其包

$visa->package({PACKAGE_UUID})->update([
    'name' => {UPDATED_PACKAGE_NAME}
]);

网站API

列出所有网站

$visa->websites->list();

通过其INTP指定的ID获取单个网站

$visa->websites->getByIntpWebsiteId({INTP_WEBSITE_ID});

创建一个网站

$visa->websites->create([
    'intpWebsiteId' => {INTP_WEBSITE_ID},
    'intpCustomerId' => {INTP_CUSTOMER_ID},
    'domain' => {INTP_WEBSITE_DOMAIN},
    'packageId' => {PACKAGE_UUID},
    'billingDate' => {ISO_DATE_STRING} (optional, defaults to current time)
]);

网站API

通过其INTP指定的ID删除一个网站

$visa->website({INTP_WEBSITE_ID})->delete());

管理订阅状态的API

升级 - 立即将更高stp计数的包应用于订阅

$visa->subscriptions->upgrade([
    "intpWebsiteId" => {INTP_WEBSITE_ID},
    "packageId" => {PACKAGE_UUID},
    "trial" => {true|false},
    "proRate" => {true|false}
])

降级 - 在当前计费周期结束时自动续订到新的更低stp计数的包

$visa->subscriptions->downgrade([
    "intpWebsiteId" => {INTP_WEBSITE_ID},
    "packageId" => {PACKAGE_UUID}
])

取消 - 在当前计费周期结束时禁用订阅自动续订

$visa->subscriptions->cancel([
    "intpWebsiteId" => {INTP_WEBSITE_ID},
])

恢复 - 在当前计费周期结束时重新启用订阅自动续订

$visa->subscriptions->resume([
    "intpWebsiteId" => {INTP_WEBSITE_ID},
])

停用 - 立即停用订阅，可以通过升级逆转

$visa->subscriptions->deactivate([
    "intpWebsiteId" => {INTP_WEBSITE_ID},
])

实用工具API

为当前INTP配置生成有效的访问令牌。

$visa->auth->generateINTPAccessToken();

为当前INTPc配置生成有效的访问令牌。

$visa->auth->generateINTPcAccessToken({INTP_CUSTOMER_ID});

仪表板iframe

iframe是用户与其网站收集的数据交互的主要方式之一。iframe的URL是通过SDK生成的

生成的URL可以通过查询参数进一步增强

1. allowUpgrade=true - 显示升级CTA

升级按钮将被添加到仪表板的所有需要一定最小包的功能中。一旦点击升级按钮，iframe将向父帧发送消息，包含以下有效载荷

{
  "type": "UPGRADE_BUTTON_CLICKED",
  "data": {
    "intpWebsiteId": "", // string; external website id
    "intpCustomerId": "", // string; customer id
    "packageName": "", // string; current package name
    "packageId": "", // string; current package id
    "inTrial": true|false, // boolean;
    "expiresAt": "", // string; expiry date in ISO 8601 format
    "billingInterval": "monthly"|"yearly" // string;
  }
}

分页

list方法支持以下分页选项

$visa->customers->list(['page' => 0, 'pageSize' => 5])

如果没有提供分页选项，则默认pageSize为10个项目。

页码计数从0开始。