Added documentation for In-App Payments API.

Added documentation for In-App Payments API.

BUG=181763
STAGED DOC: http://ypd-ubiq182.dls.corp.google.com:8000/apps/service_in_app_payments.html

R=kalman@chromium.org, saroop@chromium.org

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=210638

[Andy, 2013-07-06 02:06:54]

On 2013/07/06 02:05:42, Andy wrote:

Ben, this is my first time adding a file to the Apps doc set.  Let me know if I
need to fix anything.

Thanks,

Andy

[not at google - send to devlin, 2013-07-08 16:15:43]

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/api/...
File chrome/common/extensions/api/_permission_features.json (right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/api/...
chrome/common/extensions/api/_permission_features.json:295: },
things in chrome/common/extensions/api are only for actual chrome APIs, which
this isn't. I'll comment on the public html file with something that should
work, or should at least not require much extra effort to make work.

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html:5:
{{?api.permissions.beta}}{{+partials.warning_beta}}{{/}}
these shouldn't be necessary since it's not built into chrome .: not tied to any
version.

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/templates/json/apps_sidenav.json (right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/json/apps_sidenav.json:183: "title":
"In-App Payments API",
It's not *really* an API so just "In-App Payments"?

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/json/apps_sidenav.json:184: "href":
"/apps/service_in_app_payments.html"
a nicer URL would be just "in_app_payments.html"

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File
chrome/common/extensions/docs/templates/public/apps/service_in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/public/apps/service_in_app_payments.html:1:
{{+partials.standard_apps_article api:apis.inAppPayments
article:intros.service_in_app_payments}}
try leaving out the api:apis.inAppPayments

[saroop, 2013-07-08 21:01:48]

lgtm

[Andy, 2013-07-09 00:51:22]

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/api/...
File chrome/common/extensions/api/_permission_features.json (right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/api/...
chrome/common/extensions/api/_permission_features.json:295: },
On 2013/07/08 16:15:43, kalman wrote:
> things in chrome/common/extensions/api are only for actual chrome APIs, which
> this isn't. I'll comment on the public html file with something that should
> work, or should at least not require much extra effort to make work.

Done.

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html:5:
{{?api.permissions.beta}}{{+partials.warning_beta}}{{/}}
On 2013/07/08 16:15:43, kalman wrote:
> these shouldn't be necessary since it's not built into chrome .: not tied to
any
> version.

Done.

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File chrome/common/extensions/docs/templates/json/apps_sidenav.json (right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/json/apps_sidenav.json:183: "title":
"In-App Payments API",
On 2013/07/08 16:15:43, kalman wrote:
> It's not *really* an API so just "In-App Payments"?

Done.

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/json/apps_sidenav.json:184: "href":
"/apps/service_in_app_payments.html"
On 2013/07/08 16:15:43, kalman wrote:
> a nicer URL would be just "in_app_payments.html"

Done.

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File
chrome/common/extensions/docs/templates/public/apps/service_in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/public/apps/service_in_app_payments.html:1:
{{+partials.standard_apps_article api:apis.inAppPayments
article:intros.service_in_app_payments}}
On 2013/07/08 16:15:43, kalman wrote:
> try leaving out the api:apis.inAppPayments

Done.

[not at google - send to devlin, 2013-07-09 14:57:36]

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html:5:
{{?api.permissions.beta}}{{+partials.warning_beta}}{{/}}
On 2013/07/08 16:15:43, kalman wrote:
> these shouldn't be necessary since it's not built into chrome .: not tied to
any
> version.

My comment here is actually wrong but also right. I didn't realise that it is in
fact tied to a specific version, though that's because the app is built into
Chrome.

However, the dev/beta/stable stuff doesn't apply, right? We always install the
app?

So all we really need to say is the availability, which luckily isn't going to
change.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
File chrome/common/extensions/docs/templates/articles/in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:12: </tr>
Is the blank row necessary?

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:19:
<td>Chrome 29 or later</td>
This brings up an interesting point. Since we're going to start generating these
(though not for this API) what should the language be? We don't have to get it
right now I suppose, but it's already starting to differ (most APIs say like
"Google Chrome 29", here it's "Chrome 29 or later").

What do you think? I never really liked "Google Chrome 29", it feels awkward.

Anyway not something we need to fix right away.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:40: The
In-App Payments Service requires you to package a JavaScript file, buy.js, with
your app to trigger the purchase flow.
can you link to buy.js here? Might as well. Just turn the buy.js into a link I
mean.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:55: When
the user clicks the "Buy" button, the Google Wallet server processes the payment
and displays a purchase confirmation dialog
You have
the "Buy"
here and
a Buy
above. Can it be consistent?

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:116:
<li>You must package the <code>buy.js</code> library with your app, and load the
library from its location in your package.</li>
prefer the same <a> than <code> here.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:127: <ul
style="list-style-type: none;">
I presume this pattern is to get a little indented thing in the list? A less
verbose way of doing this, and which would reduce duplication, would be
something like:

(at the top)

<style>
  .indented {
    padding-left: 2em;  /* whatever looks the way you want */
  }
</style>

then everywhere

<ol>
  <li>Generate a JWT...
    <div class="indented">you can generate JWTs...</div>
  </li>
</ol>

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:144:
<code>buy.js</code> with your app, and load the library from the packaged
location.</li>
ditto here and above, though maybe linking to it 3 times in 1 sentence is
overkill? I dunno, see how it looks, but we should be somehow consistent with
the use of monospace vs not (I think not-monospace for the filename and just
always link it - but yeah, see how it looks).

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:195: you
must package buy.js with your app; and you must specify an additional parameter
in the call to <code>buy()</code>).
link or some common style here too?

[not at google - send to devlin, 2013-07-09 14:58:09]

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
File
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/1/chrome/common/extensions/docs...
chrome/common/extensions/docs/templates/articles/service_in_app_payments.html:5:
{{?api.permissions.beta}}{{+partials.warning_beta}}{{/}}
On 2013/07/09 14:57:36, kalman wrote:
> On 2013/07/08 16:15:43, kalman wrote:
> > these shouldn't be necessary since it's not built into chrome .: not tied to
> any
> > version.
> 
> My comment here is actually wrong but also right. I didn't realise that it is
in
> fact tied to a specific version, though that's because the app is built into
> Chrome.
> 
> However, the dev/beta/stable stuff doesn't apply, right? We always install the
> app?
> 
> So all we really need to say is the availability, which luckily isn't going to
> change.

oops this was an old comment sorry.

[Andy, 2013-07-09 20:46:53]

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
File chrome/common/extensions/docs/templates/articles/in_app_payments.html
(right):

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:12: </tr>
On 2013/07/09 14:57:36, kalman wrote:
> Is the blank row necessary?

Blank row removed.  (I copied the table from one of the API docs; I don't know
what the purpose of the blank row is.)

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:19:
<td>Chrome 29 or later</td>
On 2013/07/09 14:57:36, kalman wrote:
> This brings up an interesting point. Since we're going to start generating
these
> (though not for this API) what should the language be? We don't have to get it
> right now I suppose, but it's already starting to differ (most APIs say like
> "Google Chrome 29", here it's "Chrome 29 or later").
> 
> What do you think? I never really liked "Google Chrome 29", it feels awkward.
> 
> Anyway not something we need to fix right away.

I noticed the inconsistency between the docs.  I agree with you that "Google
Chrome XX" is awkward, and strongly prefer "Chrome XX".  Most of the docs at
google.com/chrome use plain "Chrome". 

For this doc, I removed "or later".

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:40: The
In-App Payments Service requires you to package a JavaScript file, buy.js, with
your app to trigger the purchase flow.
On 2013/07/09 14:57:36, kalman wrote:
> can you link to buy.js here? Might as well. Just turn the buy.js into a link I
> mean.

Done.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:55: When
the user clicks the "Buy" button, the Google Wallet server processes the payment
and displays a purchase confirmation dialog
On 2013/07/09 14:57:36, kalman wrote:
> You have
> the "Buy"
> here and
> a Buy
> above. Can it be consistent?

Done.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:116:
<li>You must package the <code>buy.js</code> library with your app, and load the
library from its location in your package.</li>
On 2013/07/09 14:57:36, kalman wrote:
> prefer the same <a> than <code> here.

Done.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:127: <ul
style="list-style-type: none;">
On 2013/07/09 14:57:36, kalman wrote:
> I presume this pattern is to get a little indented thing in the list? A less
> verbose way of doing this, and which would reduce duplication, would be
> something like:
> 
> (at the top)
> 
> <style>
>   .indented {
>     padding-left: 2em;  /* whatever looks the way you want */
>   }
> </style>
> 
> then everywhere
> 
> <ol>
>   <li>Generate a JWT...
>     <div class="indented">you can generate JWTs...</div>
>   </li>
> </ol>

Done, but I added the style rule in site.css for reuse (plus <style> must
technically be in the <head> section, unless you use the scoped attribute).

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:144:
<code>buy.js</code> with your app, and load the library from the packaged
location.</li>
On 2013/07/09 14:57:36, kalman wrote:
> ditto here and above, though maybe linking to it 3 times in 1 sentence is
> overkill? I dunno, see how it looks, but we should be somehow consistent with
> the use of monospace vs not (I think not-monospace for the filename and just
> always link it - but yeah, see how it looks).

Done.

https://codereview.chromium.org/18186004/diff/12001/chrome/common/extensions/...
chrome/common/extensions/docs/templates/articles/in_app_payments.html:195: you
must package buy.js with your app; and you must specify an additional parameter
in the call to <code>buy()</code>).
On 2013/07/09 14:57:36, kalman wrote:
> link or some common style here too?

Done.

[not at google - send to devlin, 2013-07-09 20:56:12]

lgtm

[Andy, 2013-07-09 21:36:41]

Committed patchset #3 manually as r210638 (presubmit successful).