README

只需几个步骤即可开始展示广告的简单自定义集成。

安装

composer require adquesto/adquesto-php-sdk

快速入门

创建具有默认值的Content以开始提供广告。

use Adquesto\SDK\Content;
use Adquesto\SDK\InMemoryStorage;
use Adquesto\SDK\CurlHttpClient;
use Adquesto\SDK\PositioningSettings;

$adquesto = new Content(
    # Adquesto API endpoint that provides latest javascript
    'https://api.adquesto.com/v1/publishers/services/',
    # Unique Service identifier
    'Paste Service UUID here',
    # Implementation that will hold javascript file contents
    new InMemoryStorage,
    new CurlHttpClient,
    PositioningSettings::factory(PositioningSettings::STRATEGY_UPPER)
);

这是一个门面，它提供了显示广告和维护其位置的完整功能。

构造函数参数包括

apiUrl Adquesto服务端点

serviceId 可以是服务UUID或用于从API获取JavaScript文件内容的可调用对象。您可以通过导航到仪表板中的服务详细信息来找到它。

storage 存储实现实例，用于存储JavaScript文件内容，以防止每次需要显示时都执行API请求。我们提供了两种实现：WordpressStorage 和 InMemoryStorage

httpClient 用于获取JavaScript的HTTP客户端实现

positioningSettings 返回用于在渲染内容时定位quest的值的PositioningSettings实例。有两个预定义的策略：PositioningSettings::STRATEGY_UPPER 和 PositioningSettings::STRATEGY_LOWER。请使用factory方法作为最佳实践。

contextProviders （可选）用于获取在渲染JavaScript文件时使用的模板值的上下文提供者数组。有一些现成的实现，例如ElementsContextProvider。

现在，我们可以获取将最终渲染广告的JavaScript文件。

use Adquesto\SDK\ElementsContextProvider;

try {
    $javascript = $adquesto->javascript([
        $elementsProvider = new ElementsContextProvider,
        new \Adquesto\SDK\SubscriptionsContextProvider,
    ]);
} catch (Adquesto\SDK\NetworkErrorException $e) {
    // Handle exception here
}

我们可以像构造函数一样传递一个上下文提供者数组。它们负责用特定于集成的值替换从API获取的JavaScript文件中的占位符。

上面的示例将返回使用随机ID作为广告容器的占位符的JavaScript源代码。然后可以通过使用以下方法获取生成的ID：

$mainQuestElementId = $elementsProviders->mainQuestId();
$reminderQuestElementId = $elementsProviders->reminderQuestId();

自动广告位置

我们提供了一种方法，可以帮助您在HTML内容内部的最佳位置放置广告。要使用它，请使用以下参数调用prepare方法：

htmlContent 是您的内容的HTML（例如，博客文章）
adContainerHtml 是容器的HTML，将包含广告（例如，<div id="$mainQuestElementId"></div>）
reminderAdContainerHtml 与上述内容相同，唯一的区别是它将包含提醒广告（<div id="$reminderQuestElementId"></div>）

注意：adContainerHtml 和 reminderAdContainerHtml 必须与获取JavaScript文件时使用的相同。

$preparedContent = $adquesto->autoPrepare(
    $htmlContent,
    $adContainerHtml,
    $reminderAdContainerHtml
);

手动广告位置

您还可以使用以下函数查找<div class="questo-should-be-inserted-here"></div>并将其替换为广告

$preparedContent = $adquesto->manualPrepare(
    $htmlContent,
    $adContainerHtml,
    $reminderAdContainerHtml
);

如果您只想检查内容中是否存在div，请使用

$hasQuesto = $adquesto->hasQuestoInContent($content);

该函数将返回内容中存在<div class="questo-here"></div>则为true。

准备好的内容

both autoPrepare 和 manualPrepare 返回PreparedContent实例，除了包含内容外，还有一个标志，指示是否可以显示广告 - isAdReady方法。

要应用JavaScript插件源

$preparedContent->setJavaScript($javascript);

概述

JavaScript存储

我们使用存储接口来沟通与JavaScript内容持久性相关的意图，而不是执行多个API调用，从而提供更好的用户体验。

WordpressStorage

使用Wordpress的get_option函数来持久化JavaScript文件内容，并将其缓存24小时。

InMemoryStorage

基本的实现，将JavaScript文件内容保存在内存中。可能仅用于原型制作。

上下文提供者

为了正确渲染显示广告的JavaScript，我们使用一个模板，该模板应填充一些重要的变量。有两个现成的实现，它们提供了良好的界面。

ElementsContextProvider

最重要的上下文提供者，它告诉用于渲染广告的HTML容器的名称。构造函数参数是可选的

mainQuestId 主要广告元素ID名称（例如：questo-container）
reminderQuestId 提醒广告元素ID（例如：questo-reminder-container）
isDraft 广告是否以草稿形式显示（默认为false）
hasActiveCampaigns bool或可调用对象，它应包含有关您的服务现有活动的信息 - 使用webhook触发更改，值在响应中，与服务状态一起

默认情况下，mainQuestId和reminderQuestId都使用随机字符串生成。

注意：对于所有测试目的，包括任何类型的CMS中的预览模式，应将isDraft设置为true。

SubscriptionsContextProvider

这提供了启用订阅功能所需的关键变量，允许通过OAuth2识别经过身份验证的读者。

$subscriberStorage = new SubscriberSessionStorage;
$subscriber = $subscriberStorage->get();
$daysLeft = $subscriber->valid_to->diff(new \DateTime)->days;

new SubscriptionsContextProvider(array(
    SubscriptionsContextProvider::IS_SUBSCRIPTION_ACTIVE => (int)$subscriber->isSubscriptionValid(),
    SubscriptionsContextProvider::IS_SUBSCRIPTION_RECURRING => (int)$isSubscriptionRecurring,
    SubscriptionsContextProvider::IS_SUBSCRIPTION_DAYS_LEFT => $daysLeft,
    SubscriptionsContextProvider::IS_SUBSCRIPTION_AVAILABLE => true,
    SubscriptionsContextProvider::AUTHORIZATION_ERROR => (string)$authorizationError,
    SubscriptionsContextProvider::IS_LOGGED_IN => $subscriber !== null,
    SubscriptionsContextProvider::AUTHORIZATION_URI => $authorizationUri,
    SubscriptionsContextProvider::LOGOUT_URI => $logoutUri,
    SubscriptionsContextProvider::USER_LOGIN => $subscriber->email,
));

订阅者支持（通过Adquesto OAuth2）

我们提供了一个OAuth2客户端，该客户端利用Adquesto后端来授权用户作为订阅者。步骤如下

生成指向Adquesto的授权链接

use Adquesto\SDK\OAuth2Client;
use Adquesto\SDK\CurlHttpClient;

$oauth2Client = new OAuth2Client(
    new CurlHttpClient,
    'client_id_here',
    'http://adquesto.com/subscriber',
    'http://api.adquesto.com/oauth2/token',
    'http://api.adquesto.com/oauth2/me',
    'your_redirect_uri'
);

$authorizationUrl = $oauth2Client->authorizationUrl();

当用户被重定向回来时，发出SubscriberManager方法，该方法将处理获取订阅者信息（包括过期日期）

$subscriberManager = new SubscriberManager($oauth2Client, new SubscriberSessionStorage);
$subsciber = $subscriberManager->handleRedirect($_GET['code']);

订阅者现在可以使用了。多亏了SubscriberSessionStorage，该信息在会话中持久化，因此每个请求都将有关于当前订阅者的信息。

注意：在涉及无广告体验的任何操作之前，运行$subscriber->isSubscriptionValid()很重要。

Webhooks

我们将向您的服务webhook URL发送包含以下操作的POST请求。以下操作之一以form-data形式发送。每个操作都代表您端需要执行的更改，以实现一致的用户体验。

您应响应JSON{"status": "OK"}。如果不这样做，我们将使用指数退避策略重试10次。

服务状态更新

操作：questo_update_service_status_option

一旦收到，您应该从API请求当前状态。示例

$serviceApiUrl = new \Adquesto\SDK\ServiceAPIUrl(
    'https://api.adquesto.com/v1/publishers/services/',
    'Paste Service UUID here'
);
$service = new \Adquesto\SDK\Service(
    $serviceApiUrl,
    new CurlHttpClient
);
$serviceStatusResponse = $service->fetchStatus();

响应中有一个数组，包含以下键

status告诉服务是否被接受（bool）

使用此键来开启和关闭任何广告显示相关的活动。

subscription表示是否启用了订阅（bool）

当获取JavaScript插件时，应使用此键，因为它指示是否开启或关闭订阅功能。

hasActiveCampaigns表示是否有符合您服务条件可以显示的活动和任务。

订阅状态更新

操作：questo_update_subscription_option

当切换订阅功能时，此操作被触发。现在，请使用与服务状态更新中描述的相同方法获取实际值。

强制JavaScript更新

操作：questo_force_update_javascript

有时我们可能会调用您的端点，以告知有新的JavaScript文件可用，以便您可以在存储中更新它。

以下示例显示了如何用新JavaScript文件替换旧的一个

$javascript = $adquesto->requestJavascript();
if ($javascript) {
    $content->getStorage()->set($javascript);
}

JavaScript事件

点击这里了解有关JavaScript事件的更多信息。

adquesto / adquesto-php-sdk

维护者

详细信息