README

该包帮助您实现 Google Ads / Adwords API 的功能。

安装

在控制台输入

composer require 5baddi/laravel-google-ads-lib

Laravel 5.5 或更高版本？

那么您不需要注册或添加别名，此包使用包自动发现功能，并且应该通过 Composer 安装后立即可用。

（仅适用于 Laravel 5.4 或更低版本）通过将其添加到 providers 数组中注册 GoogleAds 服务。

'providers' => array(
        ...
        BADDIGroup\GoogleAds\Providers\GoogleAdsServiceProvider::class
    )

（仅适用于 Laravel 5.4 或更低版本）让我们添加别名外观，将其添加到 aliases 数组中。

'aliases' => array(
        ...
        'GoogleAds' => BADDIGroup\GoogleAds\Facades\GoogleAds::class,
    )

将包的配置文件发布到应用程序的配置目录。

php artisan vendor:publish --provider="BADDIGroup\GoogleAds\Providers\GoogleAdsServiceProvider" --tag="config"

上述命令将在您的 Laravel 应用配置文件夹下生成一个名为 googleads.php 的新文件

配置

使用您的数据更新 googleads.php 文件。

'level' => 'test',
'production' => [
    'developerToken' => "YOUR-DEV-TOKEN",
    'clientCustomerId' => "CLIENT-CUSTOMER-ID",
    'userAgent' => "YOUR-NAME",
    'clientId' => "CLIENT-ID",
    'clientSecret' => "CLIENT-SECRET",
    'refreshToken' => "REFRESH-TOKEN"
],
'test' => [
    'developerToken' => "YOUR-DEV-TOKEN",
    'clientCustomerId' => "CLIENT-CUSTOMER-ID",
    'userAgent' => "YOUR-NAME",
    'clientId' => "CLIENT-ID",
    'clientSecret' => "CLIENT-SECRET",
    'refreshToken' => "REFRESH-TOKEN"
],

'level' 键接受以下值之一：test / production

生成刷新令牌

请注意，它将根据 level 值从 googleads.php 配置文件中获取 clientID 和 clientSecret。

在控制台输入

php artisan googleads:generate:refresh-token

• 访问显示的 URL，授予您的应用程序访问权限，并在控制台中输入访问令牌。
• 然后复制新鲜令牌到 googleads.php 配置文件。

请记住将此令牌复制到正确的部分（test/production）。这取决于您的 level 值。

使用示例

实例化主包装类

$ads = new GoogleAds();

不要忘记在文件顶部放置 use 语句

use BADDIGroup\GoogleAds\GoogleAds;

所有需要的配置数据都是从 googleads.php 配置文件中获取的。但您始终可以在需要时动态传递新值。

您可以通过调用 setAccessLevel 方法来覆盖默认的访问级别值

$ads->setAccessLevel('test');

您也可以通过 getAccessLevel 方法获取访问级别值

$ads->getAccessLevel();

如果需要覆盖 OAuth 详细信息，只需像这样调用 OAuth 方法

$ads->OAuth([
            'clientId' => 'test',
            'clientSecret' => 'test',
            'refreshToken' => 'TEST'

        ]);

与 session 相同。如果需要动态覆盖默认值，只需通过调用 session 方法来完成

$ads->session([
    'developerToken' => 'token',
    'clientCustomerId' => 'id'
]);

上述所有方法都可以按以下方式链式调用

$ads->setAccessLevel('test')
    ->OAuth([
        'clientId' => 'test',
        'clientSecret' => 'test',
        'refreshToken' => 'TEST'

    ])
    ->session([
        'developerToken' => 'token',
        'clientCustomerId' => 'id'
    ]);

Google 服务

对于 Google Ads 服务，您只需调用 service 方法即可

$ads->service(CampaignService::class);

或者

$ads->service(AdGroupService::class);

或者

$ads->service(AdGroupAdService::class);

或者调用 Google\AdsApi\AdWords\v201809\cm 文件夹下任何可用的 google ads 服务。

您还可以使用全局辅助器来获取 Service 的实例。

$service = googleService(CampaignService::class)

要获取活动列表，请按以下方式进行操作

$ads->service(CampaignService::class)
    ->select(['Id', 'Name', 'Status', 'ServingStatus', 'StartDate', 'EndDate'])
    ->get();

请注意，select 方法是必需的，并且您必须使用它来设置要从活动获取的字段。

如果您需要在搜索中添加条件，可以使用 where 方法如下

$ads->service(CampaignService::class)
    ->select(['Id', 'Name', 'Status', 'ServingStatus', 'StartDate', 'EndDate'])
    ->where('Id IN [752331963,795625088]')
    ->get();
or

$ads->service(CampaignService::class)
    ->select(['Id', 'Name', 'Status', 'ServingStatus', 'StartDate', 'EndDate'])
    ->where('Id = 752331963')
    ->get();

注意！您也可以设置多个条件。这样调用 where 方法，需要多少次就调用多少次。

可用运算符

= | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL

如果您需要限制搜索，可以使用 limit 方法

$ads->service(CampaignService::class)
    ->select(['Id', 'Name', 'Status', 'ServingStatus', 'StartDate', 'EndDate'])
    ->limit(5)
    ->get();
    

您还可以按字段排序

$ads->service(CampaignService::class)
    ->select(['Id', 'Name', 'Status', 'ServingStatus', 'StartDate', 'EndDate'])
    ->orderBy('Name')
    ->limit(5)
    ->get();

请注意，get 方法返回一个 ServiceCollection 实例。该自定义集合有自己的方法。

一旦您有了集合，您可以使用 where 方法再次进行筛选

$campaignService = $ads->service(CampaignService::class);

$results = $campaignService->select('CampaignId','CampaignName')->get();

//You can also add any where condition on the list.
$campaign = $results->where('id',1341312);

您还可以调用 set 方法来更改任何值

$campaign = $results->where('id',$this->testedCampaignId)->set('name','hello !!');

最后，您可以使用 save 方法持久化这些更改

$campaign = $campaign->save();

save 方法返回更新元素数组或如果没有任何更新则返回 false。

重要!! 注意，它将持久化集合中的所有元素。

您可以通过调用 items 方法简单地以 illuminate collection 的形式获取列表。

Google 报告

要开始使用 Google 报告，只需从主包装中调用 report 方法即可

$report = $ads->report();

或者使用如下所示的全球辅助工具

$report = googleReport();

它将返回一个 BADDIGroup\GoogleAds\Reports\Report 实例

现在，你有一组方法来准备谷歌广告报告

$obj = $ads->report()
            ->from('CRITERIA_PERFORMANCE_REPORT')
            ->during('20170101','20170210')
            ->where('CampaignId = 752331963')
            ->select('CampaignId','AdGroupId','AdGroupName','Id', 'Criteria', 'CriteriaType','Impressions', 'Clicks', 'Cost', 'UrlCustomParameters')
            ->getAsObj();

在上面的方法中，必须的参数是 from 和 select

请注意，在 during 方法中，你必须以字符串形式传递日期，例如 YearMonthDay

你可能还需要设置多个条件。根据需要多次使用 Where 子句，如下所示

$obj = $ads->report()
            ->from('CRITERIA_PERFORMANCE_REPORT')
            ->where('Clicks > 10')
            ->where('Cost > 10')
            ->where('Impressions > 1')
            ->select('CampaignId','AdGroupId','AdGroupName','Id', 'Criteria', 'CriteriaType','Impressions', 'Clicks', 'Cost', 'UrlCustomParameters')
            ->getAsObj();

可用运算符

= | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL

想要排除任何字段？只需这样做

$obj = $ads->report()
           ->from('SHOPPING_PERFORMANCE_REPORT')
           ->select(\BADDIGroup\GoogleAds\Facades\GoogleAds::fields()->of('SHOPPING_PERFORMANCE_REPORT')->asList())
           ->except('SearchImpressionShare','ExternalConversionSource','Ctr','Cost','Date','Week','Year','AverageCpc','Clicks','ClickType','ConversionCategoryName','ConversionTrackerId','ConversionTypeName')
            ->getAsObj();

如果想要查看检索到的项目，只需通过对象返回的 result 属性来获取

$items = $obj->result;

请注意，它是一个集合。因此，你可以使用所有集合方法。

如果需要以其他格式报告，请在获取报告之前调用 format 方法

$string = $ads->report()
            ->format('CSVFOREXCEL')
            ->select('CampaignId','AdGroupId','AdGroupName','Id', 'Criteria', 'CriteriaType','Impressions', 'Clicks', 'Cost', 'UrlCustomParameters')
            ->from('CRITERIA_PERFORMANCE_REPORT')
            ->getAsString();

要查看可用的报告格式

$ads->report()->getFormats()

要查看特定报告类型可用的字段，可以这样做

$fields = $ads->report()->from('CRITERIA_PERFORMANCE_REPORT')->getFields();

如果想知道可用的报告类型，只需这样做

$ads->report()->getTypes();

报告有 3 种输出格式。可以是对象、流或字符串。

getAsString();
getStream();
getAsObj();

你还可以将报告保存到文件中

$saved = $ads->report()
             ->select('CampaignId','AdGroupId','AdGroupName','Id', 'Criteria', 'CriteriaType','Impressions', 'Clicks', 'Cost', 'UrlCustomParameters')
             ->from('CRITERIA_PERFORMANCE_REPORT')
             ->saveToFile($filePath)

上述代码将在指定的路径创建一个文件，如果一切正常则返回 true。