README

只需几个步骤即可轻松自定义集成，开始显示广告。

安装

composer require questpass/questpass-php-sdk

快速开始

创建带有默认值的 Content 以开始投放广告。

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

$questpass = new Content(
    # Questpass API endpoint that provides latest javascript
    'https://api.questpass.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 Questpass服务端点

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

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

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

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

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

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

use Questpass\SDK\ElementsContextProvider;

try {
    $javascript = $questpass->javascript([
        $elementsProvider = new ElementsContextProvider,
        new \Questpass\SDK\SubscriptionsContextProvider,
    ]);
} catch (Questpass\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 = $questpass->autoPrepare(
    $htmlContent,
    $adContainerHtml,
    $reminderAdContainerHtml
);

手动广告定位

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

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

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

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

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

准备好的内容

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

要应用JavaScript插件源代码

$preparedContent->setJavaScript($javascript);

概述

JavaScript存储

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

WordpressStorage

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

InMemoryStorage

基本实现，将JavaScript文件内容存储在内存中。很可能仅用于poc测试。

上下文提供者

为了正确渲染显示广告的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,
));

订阅者支持（通过Questpass OAuth2）

我们提供了一个OAuth2客户端，该客户端利用Questpass后端对用户进行订阅者授权。步骤如下

生成Questpass的授权链接

use Questpass\SDK\OAuth2Client;
use Questpass\SDK\CurlHttpClient;

$oauth2Client = new OAuth2Client(
    new CurlHttpClient,
    'client_id_here',
    'http://questpass.com/subscriber',
    'http://api.questpass.com/oauth2/token',
    'http://api.questpass.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请求。每个操作代表您端需要执行的操作以实现连贯的体验。

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

服务状态更新

操作：questo_update_service_status_option

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

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

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

status 表示服务是否被接受（bool）

使用此键可以打开和关闭任何与广告显示相关的活动。

subscription 是否启用了订阅（bool）

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

hasActiveCampaigns 是否有任何服务可以显示的活动和任务。

订阅状态更新

操作：questo_update_subscription_option

当订阅功能打开或关闭时，会触发此操作。现在，请使用与Service状态更新中描述的相同的方法来获取实际值。

强制JavaScript更新

操作：questo_force_update_javascript

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

以下示例显示了如何用新JavaScript替换旧JavaScript的详细信息

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

JavaScript事件

点击此处了解有关JavaScript事件的更多信息。

questpass / questpass-php-sdk

维护者

详细信息