-
Notifications
You must be signed in to change notification settings - Fork 64
/
README.rtf
279 lines (231 loc) · 12.1 KB
/
README.rtf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
{\rtf1\ansi\ansicpg1252\cocoartf1187\cocoasubrtf390
{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fmodern\fcharset0 Courier;\f2\fmodern\fcharset0 Courier-Oblique;
\f3\fnil\fcharset0 LucidaGrande;}
{\colortbl;\red255\green255\blue255;\red255\green255\blue255;\red38\green38\blue38;\red246\green246\blue246;
\red100\green100\blue100;\red52\green110\blue183;}
{\*\listtable{\list\listtemplateid1\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid1\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid1}
{\list\listtemplateid2\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid101\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{circle\}}{\leveltext\leveltemplateid102\'01\uc0\u9702 ;}{\levelnumbers;}\fi-360\li1440\lin1440 }{\listname ;}\listid2}
{\list\listtemplateid3\listhybrid{\listlevel\levelnfc23\levelnfcn23\leveljc0\leveljcn0\levelfollow0\levelstartat1\levelspace360\levelindent0{\*\levelmarker \{disc\}}{\leveltext\leveltemplateid201\'01\uc0\u8226 ;}{\levelnumbers;}\fi-360\li720\lin720 }{\listname ;}\listid3}}
{\*\listoverridetable{\listoverride\listid1\listoverridecount0\ls1}{\listoverride\listid2\listoverridecount0\ls2}{\listoverride\listid3\listoverridecount0\ls3}}
\margl1440\margr1440\vieww10800\viewh8400\viewkind0
\deftab720
\pard\pardeftab720\sa200
\f0\b\fs56 \cf0 \cb2 AwReporting\
\pard\pardeftab720\sa200
\fs48 \cf0 Overview\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 AwReporting is an open-source Java framework for large scale AdWords API reporting.\
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl440\sa300
\ls1\ilvl0\cf3 {\listtext \'95 }You can use this project to generate reports for all the AdWords accounts managed by an MCC.\
{\listtext \'95 }15 common reports are included in the reference implementation. You can easily follow the code examples to implement more.\
{\listtext \'95 }Reports are stored in your
\b relational database
\b0 , so you can integrate them with your existing systems.\
\pard\pardeftab720\sa200
\b\fs48 \cf0 Quick Start\
\pard\pardeftab720\sa200
\fs36 \cf3 Prerequisites\
\pard\tx720\pardeftab720\sl440
\b0\fs28 \cf3 You will need Java, Maven and MySQL installed before configuring the project.\
\
\pard\pardeftab720\sa200
\b\fs36 \cf3 Build the project using Maven\
\pard\pardeftab720\sl440\sa300
\f1\b0\fs24 \cf3 \cb4 $ git clone https://github.com/googleads/aw-reporting
\f0\fs28 \cb2 \
\f1\fs24 \cb4 $ cd aw-reporting
\f0\fs28 \cb2 \
\f1\fs24 \cb4 $ cd aw-report-model
\f0\fs28 \cb2 \
\f1\fs24 \cb4 $ mvn clean install eclipse:eclipse
\f0\fs28 \cb2 \
\f1\fs24 \cb4 $ cd ../aw-reporting
\f0\fs28 \cb2 \
\f1\fs24 \cb4 $ mvn eclipse:eclipse
\f0\fs28 \cb2 \
\f1\fs24 \cb4 $ mvn compile dependency:copy-dependencies package
\f0\fs28 \cb2 \
\pard\pardeftab720\sa200
\b\fs36 \cf3 Configure your MySQL database\
\pard\pardeftab720\sl440\sa300
\f1\b0\fs24 \cf3 \cb4 CREATE DATABASE AwReporting DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8
\f2\i general
\f1\i0 ci;
\f0\fs28 \cb2 \
\f1\fs24 \cb4 CREATE USER 'reportuser'@'localhost' IDENTIFIED BY 'SOME_PASSWORD';
\f0\fs28 \cb2 \
\f1\fs24 \cb4 GRANT ALL PRIVILEGES ON AwReporting.* TO 'reportuser'@'localhost' WITH GRANT OPTION;
\f0\fs28 \cb2 \
\pard\pardeftab720\sa200
\b\fs36 \cf3 Configure AwReporting\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 Now we'll create a properties file to specify your MCC, developer token, OAuth, and database credentials.\
\pard\pardeftab720\sl440\sa300
\f1\fs24 \cf3 \cb4 $ vi ../aw-reporting/src/main/resources/aw-report-sample.properties
\f0\fs28 \cb2 \
Fill in the following fields with your MCC acount ID, and developer token.\
\pard\pardeftab720\sl440\sa300
\cf5 mccAccountId=\
\pard\pardeftab720\sl440
\cf5 developerToken=\
\pard\pardeftab720\sl440\sa300
\cf3 Fill in your OAuth credentials. If you need to create them, visit: {\field{\*\fldinst{HYPERLINK "http://tmpvar.com/markdown.html"}}{\fldrslt \cf6 https://code.google.com/apis/console#access}}\
\pard\pardeftab720\sl440\sa300
\cf5 clientId=\
\pard\pardeftab720\sl440
\cf5 clientSecret=\
\pard\pardeftab720\sl440\sa300
\cf3 Fill in the following with your database connection.\
\pard\pardeftab720\sl440\sa300
\cf5 aw.report.model.db.sql.url=jdbc:mysql://localhost:3306/AWReporting?rewriteBatchedStatements=true\
aw.report.model.db.sql.username=reportuser\
\pard\pardeftab720\sl440
\cf5 aw.report.model.db.sql.password=SOME_PASSWORD\
\pard\pardeftab720\sa200
\b\fs36 \cf3 Import the project into Eclipse (optional)\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 To import the project into Eclipse, first import the model:\
\pard\pardeftab720\sl440\sa300
\cf5 File -> Import -> General -> Existing projects into workspace.\
\pard\pardeftab720\sl440
\cf5 aw-reporting/aw-report-model\
\pard\pardeftab720\sl440\sa300
\cf3 Next import the database code:\
\pard\pardeftab720\sl440\sa300
\cf5 File -> Import -> General -> Existing projects into workspace.\
\pard\pardeftab720\sl440
\cf5 aw-reporting/aw-reporting\
\pard\pardeftab720\sa200
\b\fs36 \cf3 Command line options\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 Set the following command line options before running the project:\
\pard\pardeftab720\sl380
\f1\fs24 \cf3 \cb4 java -Xmx1G -jar aw-reporting.jar -startDate YYYYMMDD -endDate YYYYMMDD -file <file>
\fs26 \
\
\fs24 java -Xmx1G -jar aw-reporting.jar -generatePdf <htmlTemplateFile> <outputDirectory> -startDate YYYYMMDD -endDate YYYYMMDD -file <file>
\fs26 \
\
\
\fs24 Arguments:\
\
-dateRange ReportDefinitionDateRangeType.\
\
-endDate <YYYMMDD> End date for CUSTOM_DATE Reports (YYYYMMDD)\
\
-file <file> aw-report-sample.properties file.\
\
-generatePdf <htmlTemplateFile> <outputDirectory>\
\
Generate Monthly Account Reports for all Accounts in PDF\
\
NOTE: For PDF use aw-report-sample-for-pdf.properties instead, the fields need to be different.\
\
-help Print this message.\
\
-startDate <YYYYMMDD> Start date for CUSTOM_DATE Reports (YYYYMMDD).\
\
\pard\pardeftab720\sl380
\fs26 \cf3 \
\pard\pardeftab720\sa200
\f0\b\fs36 \cf3 \cb2 Run the project and verify it's working\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 It's possible to run the project using either Eclipse or the command line. If using Eclipse, open and run:\
\pard\pardeftab720\sl440
\cf5 aw-reporting/src/main/java/com/google/api/ads/adwords/jaxws/extensions/AwReporting.java\
\pard\pardeftab720\sl440\sa300
\cf3 Be sure to specify the properties file you edited above on the command line.\
As it's running, the project will provide status messages about the reports it's downloading on the command line.\
Check your database when the run finishes to be sure it's been populated with the reporting data, e.g.:\
\pard\pardeftab720\sl440
\cf5 SELECT * FROM AwReporting.AW_ReportAd limit 1;\
\pard\pardeftab720\sa200
\b\fs48 \cf0 Details about the code\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 For better organization and encapsulation, the project groups the reporting workflow into two parts:
\b Aw-Report-Model
\b0 for the logic (API services, downloader and processors) and
\b Aw-Reporting
\b0 for persistence, entities and the CSV mapping to AdWords information.\
\pard\pardeftab720\sa200
\b\fs36 \cf3 Aw-Report-Model\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 Provides all the necessary classes to persist data and the entities\'92 mapping to AdWords report data.\
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl440\sa300
\ls2\ilvl0
\b \cf3 {\listtext \'95 }Entities:
\b0 these POJOs define all the available fields for each report kind as java fields, by using annotations. The Entities contain the information to link the java fields to the report fields definition, the csv display name header fields and the datastore fields.\
\ls2\ilvl0
\b {\listtext \'95 }CSV:
\b0 The CSV classes use the OpenCSV library to convert CSV files into Java beans using annotations. The package also contains two new annotations to define the Report Definition Type and the mapping between java field, report\'92s Column Name and Display Name headers. For example:\
\pard\tx940\tx1440\pardeftab720\li1440\fi-1440\sl440\sa300
\ls2\ilvl1\cf3 {\listtext
\f3 \uc0\u9702
\f0 }Annotation
\b @CsvReport
\b0 at the Report class level, for example for ReportAccount:
\f1\fs24 \cb4 @CsvReport(value= ReportDefinitionReportType.ACCOUNT
\f2\i PERFORMANCE
\f1\i0 REPORT) public class ReportAccount extends Report \{...
\f0\fs28 \cb2 \
{\listtext
\f3 \uc0\u9702
\f0 }Annotation
\b @CsvField
\b0 at the java field level, for example for avgCpm:
\f1\fs24 \cb4 @CsvField (value = "Avg. CPM", reportField = "AverageCpm") public BigDecimal avgCpm;
\f0\fs28 \cb2 \
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl440\sa300
\ls2\ilvl0
\b \cf3 {\listtext \'95 }Persistence:
\b0 The persistence layer uses Spring for bean management, injection and in class annotations, this helps to clearly demarcate the application layers. AuthTokenPersister: is the interface for the authorization token storage, we have implemented it for Mysql and a MongoDB. ReportEntitiesPersister is the interface for the report entities storage, we have implemented it for Mysql and a MongoDB.\
\pard\pardeftab720\sa200
\b\fs36 \cf3 Aw-Reporting\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 Provides the logic (API services, downloader and processors)\
\pard\tx220\tx720\pardeftab720\li720\fi-720\sl440\sa300
\ls3\ilvl0
\b \cf3 {\listtext \'95 }Downloader:
\b0 Based on MultipleClientReportDownloader java example (it uses the Library ReportDownloader) the Downloader is on charge of downloading all the report files using multiple threads.\
\ls3\ilvl0
\b {\listtext \'95 }Processors:
\b0 The ReportProcessor is the class with the main logic, it is responsible for calling the downloader, use the CVS classes for the parsing and call the Persistence helpers for the storage. This class can be replace by a custom processor by changing the bean component in the projects xml configuration files.\
\ls3\ilvl0
\b {\listtext \'95 }API Services:
\b0 Beside the report Downloader calls to AdHoc Reports, the ManagedCustomerDelegate is the only class talking to the AdWords API, it is on charge of getting all the account ids in the MCC tree.\
\ls3\ilvl0
\b {\listtext \'95 }AwReporting main:
\b0 The AwReporting main class is on charge of printing the help information, the properties file example and of passing the command line parameters to the processor for execution.\
\pard\pardeftab720\sa200
\b\fs48 \cf0 PDF Generation\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 PDF generation works monthly and also needs the use of a HTML template like ACCOUNT_PERFORMANCE_REPORT.tmpl\
First run the the date range without the -generatePdf to download the data needed to generate them.\
Here's an example properties file for PDF generation:\
\pard\pardeftab720\sl440
\cf5 aw-report-sample-for-pdf.properties\
\pard\pardeftab720\sa200
\b\fs36 \cf3 Fine print\
\pard\pardeftab720\sl440\sa300
\b0\fs28 \cf3 Pull requests are very much appreciated. Please sign the {\field{\*\fldinst{HYPERLINK "http://code.google.com/legal/individual-cla-v1.0.html"}}{\fldrslt \cf6 Google Code contributor license agreement}} (There is a convenient online form) before submitting.\
\pard\pardeftab720\sl440
\i\b \cf3 Authors\
\pard\pardeftab720\sl440
{\field{\*\fldinst{HYPERLINK "https://plus.google.com/+JulianCToledo/"}}{\fldrslt
\i0\b0 \cf6 Julian Toledo (Google Inc.)}}
\i0\b0 \
\pard\pardeftab720\sl440
{\field{\*\fldinst{HYPERLINK "https://plus.google.com/+GustavoMenezes/"}}{\fldrslt \cf6 Gustavo Menezes (Google Inc.)}}\
\pard\pardeftab720\sl440
\i\b \cf3 Copyright\
\pard\pardeftab720\sl440
\i0\b0 \cf3 Copyright \'a9 2013 Google, Inc.\
\pard\pardeftab720\sl440
\i\b \cf3 License\
\pard\pardeftab720\sl440
\i0\b0 \cf3 Apache 2.0\
\pard\pardeftab720\sl440
\i\b \cf3 Limitations\
\pard\pardeftab720\sl440
\i0\b0 \cf3 This is example software, use with caution under your own risk.\
}