README

为您的 Google Adwords 提供简单易用的 API。

安装

在控制台输入

composer require edujugon/laravel-google-ads

Laravel 5.5 或更高版本？

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

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

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

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

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

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

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

上述命令将在您的 Laravel 应用配置文件夹中生成一个名为 google-ads.php 的新文件。

配置

使用您的数据更新 google-ads.php 文件。

'env' => '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"
],

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

生成刷新令牌

请注意，它将根据 env 值从 google-ads.php 配置文件中获取 clientID 和 clientSecret。

在控制台输入

php artisan googleads:token:generate

• 访问它显示的 URL，授权您的应用程序并输入控制台中的访问令牌。
• 然后，将新令牌复制到 google-ads.php 配置文件中。

请记住，在正确的部分（test/production）复制该令牌。这取决于您的 env 值。

使用示例

实例化主要包装类

$ads = new GoogleAds();

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

use Edujugon\GoogleAds\GoogleAds;

所有需要的配置数据都从 google-ads.php 配置文件中获取。但如果需要，您也可以即时传递新值。

您可以通过调用 env 方法覆盖默认环境值

$ads->env('test');

您也可以通过 getEnv 方法获取环境值

$ads->getEnv();

如果需要覆盖 oAuth 详细信息，只需按如下方式调用 oAuth 方法

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

        ]);

同样，对于会话。如果需要即时覆盖默认值，只需通过调用 session 方法即可

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

所有上述方法都可以按如下方式链接

$ads->env('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 = google_service(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 集合。

Google 报告

首先，要使用 Google 报告，只需从主包装器中调用 report 方法

$report = $ads->report();

或者使用以下全局助手

$report = google_report();

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

现在，你有一系列方法来准备 Google 广告报告

$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(\Edujugon\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。

API 文档

完整 API 列表