Google Apps Platform

Application Manifest

Note: There's a new Google Apps Marketplace experience! Beginning November 19, 2013, new listings may only be created using the new version: existing developers may need to create a new Chrome Web Store account to publish new listings. Refer to the new documentation for more information.

An application manifest is an XML file that defines the structure and content of your application, including how your application integrates with Google Apps and is one of the steps involved in creating a listing.

This document shows an example of how to create an application manifest for an application developed for the Google Apps Marketplace or an in-house application using the Google Apps extensions console.

For an example manifest that describes a Gmail contextual gadget, see Writing the manifest in the Gmail Contextual Gadgets Developer's Guide.

Contents

Audience

This document is intended for programmers who are listing applications in the Google Apps Marketplace or developing in-house applications in the Google Apps Console. It provides an overview of the application manifest XML syntax and examples.

Example

The following is an example manifest file that describes an application that requires access to Google Calendar API.

<?xml version="1.0" encoding="UTF-8" ?>
<ApplicationManifest xmlns="http://schemas.google.com/ApplicationManifest/2009">

  <!-- Support info to show in the marketplace & control panel -->
  <Support>
    <!-- URL for application setup as an optional redirect during the install -->
    <Link rel="setup" href="http://www.example.com/google/setup.php?domain=${DOMAIN_NAME}" />

    <!-- URL for application configuration, accessed from the app settings page in the control panel -->
    <Link rel="manage" href="http://www.example.com/google/admin.php?domain=${DOMAIN_NAME}" />

    <!-- URL explaining how customers get support. -->
    <Link rel="support" href="http://www.example.com/google/support.php" />

    <!-- URL that is displayed to admins during the deletion process, to specify policies such as data retention, how to claim accounts, etc. -->
    <Link rel="deletion-policy" href="http://www.example.com/google/deletion-policy.php" />
  </Support>

  <!-- Name and description pulled from message bundles -->
  <Name>AppTest</Name>
  <Description>A simple application for testing the marketplace</Description>

  <!-- Show this link in Google's universal navigation for all users -->
  <Extension id="navLink" type="link">
    <Name>AppTest</Name>
    <Url>http://www.example.com/home.php?from=google&amp;domain=${DOMAIN_NAME}</Url>
    <!-- This app also uses the Calendar API -->
    <Scope ref="calendarFeed"/>
  </Extension>

  <!-- Declare our OpenID realm so our app is white listed -->
  <Extension id="realm" type="openIdRealm">
    <Url>http://www.example.com</Url>
  </Extension>

  <!-- Need access to the Calendar feed -->
  <Scope id="calendarFeed">
    <Url>http://www.google.com/calendar/feeds/</Url>
    <Reason>This application shows the next Calendar event.</Reason>
  </Scope>

</ApplicationManifest>

Modifications for Billing Support

If your application will support billing, you may use the syntax demonstrated above, but with one addition. The Marketplace supports the concept of "editions", which are groups of extensions. As part of the billing feature, you may charge different amounts for different editions.

To assign extensions to editions, edit your application manifest and add one or more <Edition> tags — one for each variation of your product where you want to provide only a subset of the extensions declared in the application manifest. Inside each <Edition> tag, say which of your extensions are available for that edition; you can include anything declared in an <Extension> tag in the same manifest. If you don't provide any <Edition> tags, Google will automatically insert a default edition named default_edition that includes all the extensions defined in your manifest.

In order to allow customers to purchase additional seats to your application, use the new <Link rel="add-seats" ... /> tag in the <Support> section of the application manifest.

The following manifest reproduces the above manifest with the following additions:

  • A default_edition that maintains a set of extensions for existing users
  • A standard edition that matches the features of the default_edition

    Note:In this document, the Google Apps for free edition is sometimes referred to as Standard Edition.

  • A pro edition that adds a Gmail contextual gadget
  • A link for customers to purchase additional seats
<?xml version="1.0" encoding="UTF-8" ?>
<ApplicationManifest xmlns="http://schemas.google.com/ApplicationManifest/2009">

  <!-- Support info to show in the marketplace & control panel -->
  <Support>
    <!-- URL for application setup as an optional redirect during the install -->
    <Link rel="setup" href="http://www.example.com/google/setup.php?domain=${DOMAIN_NAME}" />

    <!-- URL for application configuration, accessed from the app settings page in the control panel -->
    <Link rel="manage" href="http://www.example.com/google/admin.php?domain=${DOMAIN_NAME}" />

    <!-- URL explaining how customers get support. -->
    <Link rel="support" href="http://www.example.com/google/support.php" />

    <!-- URL that is displayed to admins during the deletion process, to specify policies such as data retention, how to claim accounts, etc. -->
    <Link rel="deletion-policy" href="http://www.example.com/google/deletion-policy.php" />

    <!-- URL that is displayed to customers so that they may purchase additional seats. -->
    <Link rel="add-seats" href="http://www.example.com/purchase"/>
  </Support>

  <!-- Name and description pulled from message bundles -->
  <Name>AppTest</Name>
  <Description>A simple application for testing the marketplace</Description>

  <!-- Show this link in Google's universal navigation for all users -->
  <Extension id="navLink" type="link">
    <Name>AppTest</Name>
    <Url>http://www.example.com/home.php?from=google&amp;domain=${DOMAIN_NAME}</Url>
    <!-- This app also uses the Calendar API -->
    <Scope ref="calendarFeed"/>
  </Extension>

  <!-- Declare our OpenID realm so our app is white listed -->
  <Extension id="realm" type="openIdRealm">
    <Url>http://www.example.com</Url>
  </Extension>

  <!-- Need access to the Calendar feed -->
  <Scope id="calendarFeed">
    <Url>http://www.google.com/calendar/feeds/</Url>
    <Reason>This application shows the next Calendar event.</Reason>
  </Scope>

  <!-- Gmail contextual gadget extractor -->

  <Extension id="extractor" type="contextExtractor">
    <Name>Hello World</Name>
    <Url>google.com:HelloWorld</Url>
    <Triggers ref="gadget"/>
    <Scope ref="emailSubject"/>
    <Scope ref="emailBody"/>
    <Container name="mail"/>
  </Extension>

  <!-- Gmail contextual gadget -->

  <Extension id="gadget" type="gadget">
    <Name>Hello World Gmail contextual gadget</Name>
    <Url>http://example.com/gadgets/hello_world_gadget.xml</Url>
    <Container name="mail"/>
  </Extension>

  <!-- Gmail contextual gadget scopes -->

  <Scope id="emailSubject">
    <Url>tag:google.com,2010:auth/contextual/extractor/SUBJECT</Url>
    <Reason>This application searches the Subject: line of each email
    for the text "Hello World."</Reason>
  </Scope>

  <Scope id="emailBody">
    <Url>tag:google.com,2010:auth/contextual/extractor/BODY</Url>
    <Reason>This application searches the message body of each email
    for the text "Hello World."</Reason>
  </Scope>

  <!-- Configures the default_edition for existing users -->
  <Edition id="default_edition">
    <Name>Default Edition</Name>
    <Extension ref="navLink"/>
    <Extension ref="realm"/>
  </Edition>

  <!-- Configures extensions available for the standard edition of the application. -->
  <Edition id="standard">
    <Name>Standard Edition</Name>
    <Extension ref="navLink"/>
    <Extension ref="realm"/>
  </Edition>

  <!-- Configures extensions available for the pro edition of the application -->
  <Edition id="pro">
    <Name>Pro Edition</Name>
    <Extension ref="navLink"/>
    <Extension ref="realm"/>
    <Extension ref="gadget"/>
    <Extension ref="extractor"/>
  </Edition>

</ApplicationManifest>

XML Tag Definitions

This section contains definitions for the XML tags used in the application manifest.

ApplicationManifest
Definition

The <ApplicationManifest> tag encapsulates the manifest definition.

Example <ApplicationManifest xmlns="http://schemas.google.com/ApplicationManifest/2009">
Subtags Locale, Name, Description, VerifiedSite, Support, Extension, Scope
Content Format Container
Container
Definition

The <Container> tag defines the web application container that runs an extension.

Example <Container name="mail"/>
Attributes
Name Format Description
name Text The name of the web application container. For example, a Gmail contextual gadget uses the container name mail.
Subtag of Extension
Content Format Complex
Description
Definition

The <Description> tag supplies a brief display tagline about the application or extension.

Example <Description>A simple application for testing the marketplace</Description>
Attributes
Name Format Description
msgId Text (Optional) The name of a message in a localization message bundle. Example: <Description msgId="app_description"/>. Enables translation into any language for which the manifest contains a Locale tag.
language Text (Optional) An ISO 639 language code. Use to set up localized text within the manifest rather than using message bundles. Do not use with msgId. Example:
<Description>Prints "Hello World"</Description>
<Description language="es">Imprime "Hola Mundo"</Description>
country Text (Optional) An ISO-3166 country code. Use with language to provide country-specific localization. Do not use with msgId. Example:
<Description language="es" country="MX">Imprime "Hola México"</Description>
Subtag of ApplicationManifest, Extension
Content Format String
Edition
Definition

The <Edition> tag encapsulates the set of extensions that belong to a given edition.

Example <Edition id="standard">
Attributes
Name Format Description
id Text The id of the Edition, used by the billing and licensing APIs to identify the Edition.
Subtags Extension, Name
Content Format Container
Extension
Definition

The <Extension> tag defines a single component of the application. An extension represents a part of your application that integrates with and extends Google Apps. These can include things like URLs in Google's universal navigation.

Example <Extension id="navLink" type="link">
Attributes
Name Format Description
id Text The id attribute provides a unique identifier for the extension.
ref Text The ref attribute is used to reference an id from within an Edition element.
type Text The type attribute describes the type of extension.
  • link—the Extension is describing a link to the application to be used in Google's universal navigation. The Url element value will be a link to the application and the Name element value will be the text used to present the link.
  • openIdRealm—the Extension is describing the OpenID realm of the application. The Url element value will be the OpenID realm and allows the site to be whitelisted. The OpenID realm in the manifest file must precisely match the realm sent with all OpenID requests in order for the whitelisting to occur. For details on how OpenID SSO works, see the OpenID SSO documentation.
  • contextExtractor—the Extension is describing an extractor for a Gmail contextual gadget. The Url element will be the extractor ID, the Param element will be a filter for the extractor output, the Triggers element will be a gadget id, and the Container name must be mail. See Writing the manifest in the Gmail Contextual Gadgets Developer's Guide.
  • gadget— the Extension is describing the gadget spec of a Gmail contextual gadget. The Url element will be a link to the gadget spec file and the Container name must be mail. See Writing the manifest in the Gmail Contextual Gadgets Developer's Guide.
Subtag of ApplicationManifest
Subtags Container, Description, Name, Param, Reason, Scope, Triggers, Url
Content Format Complex
Link
Definition

The <Link> tag provides a reference to support for the given application.

Example <Link rel="setup" href="http://www.example.com/google/setup.php?domain=${DOMAIN_NAME}" />
Attributes
Name Format Description
rel Text The rel attribute describes the relationship of the link application support.
  • If the value of the rel attribute is setup, then the href attribute value will be a link to the optional setup page encountered during the optional step 3 of installation.
  • If the value of the rel attribute is manage, then the href attribute value will be the URL for application configuration, accessed from the application settings page in the control panel.
  • If the value of the rel attribute is deletion-policy, then the href attribute value will be the URL that is displayed to administrators during the deletion process, to specify policies such as data retention, how to claim accounts, etc.
  • If the value of the rel attribute is support, then the href attribute value will be a URL on the application developer's site that has details on how customers may obtain support.
  • If the value of the rel attribute is add-seats, then the href attribute value will be a URL on the application developer's site where the user may perform an upgrade of an existing license.
href Text The href attribute provides the URL described by the rel attribute. This URL may optionally include ${DOMAIN_NAME}, which will be replaced with the domain of the currently authenticated user at runtime.
Subtag of Support
Content Format Complex
Locale
Definition

The <Locale> tag adds an external message bundle, supporting external definitions of localized content. The format of the message bundle is the same as used by OpenSocial gadgets (see Message Bundles). To activate localization of any translatable text within the application manifest, use the msgId attribute to refer to the name of a message that exists in a declared message bundle. The msgId attribute is is available in the Description, Name, and Reason elements.

Example <Locale messages="http://www.example.com/us_ALL_messages.xml" lang="en" country="US" />
Attributes
Name Format Description
messages Text The messages attribute provides an absolute URL to a message bundle. The URL must be publicly accessible.
lang Text (Optional) An ISO 639 language code.
country Text (Optional) An ISO-3166 country code.
Subtag of ApplicationManifest
Content Format Complex
Name
Definition

The <Name> tag supplies the name of the application, extension, or edition.

Example <Name>AppTest</Name>
Attributes
Name Format Description
msgId Text (Optional) The name of a message in a localization message bundle. Example: <Name msgId="app_name"/>. Enables translation into any language for which the manifest contains a Locale tag.
language Text (Optional) An ISO 639 language code. Use to set up localized text within the manifest rather than using message bundles. Do not use with msgId. Example:
<Name>Hello World</Name>
<Name language="es">Hola Mundo</Name>
country Text (Optional) An ISO-3166 country code. Use with language to provide country-specific localization. Do not use with msgId. Example:
<Name language="es" country="MX">Hola México</Name>
Subtag of ApplicationManifest, Edition, Extension
Content Format String
Param
Definition

The <Param> tag defines a name/value pair to be applied as a parameter when running an Extension.

Example <Param name="hello" value="H[a-z]* W[a-z]*"/>
Attributes
Name Format Description
name Text The name of the parameter. For example, in a Gmail contextual gadget, this can be the name of an output field from an email content extractor.
value Text The value of the parameter. For example, in a Gmail contextual gadget, this can be a regular expression defining a filter on an extractor output field.
Subtag of Extension
Content Format Complex
Reason
Definition

The <Reason> tag explains why the scope is requested by the application. This reason will be listed to the domain administrator during installation.

Example <Reason>This application shows the next Calendar event.</Reason>
Attributes
Name Format Description
msgId Text (Optional) The name of a message in a localization message bundle. Example: <Reason msgId="reason_for_scope"/>. Enables translation into any language for which the manifest contains a Locale tag.
language Text (Optional) An ISO 639 language code. Use to set up localized text within the manifest rather than using message bundles. Do not use with msgId. Example:
<Reason>Shows calendar events</Reason>
<Reason language="es">Muestra los eventos del calendario</Reason>
country Text (Optional) An ISO-3166 country code. Use with language to provide country-specific localization. Do not use with msgId. Example:
<Reason language="es" country="MX">Muestra los eventos Méxicanos del calendario</Reason>
Subtag of Scope
Content Format String
Scope
Definition

The <Scope> tag defines one of the following: a data feed to which an extension needs access for 2-legged OAuth, or an email part to which a content extractor needs access for a Gmail contextual gadget. See supported scopes.

Example <Scope id="calendarFeed">
Attributes
Name Format Description
id Text The id attribute provides a unique identifier for the scope.
ref Text The ref attribute is used to reference an id from within an Extension element.
Subtag of ApplicationManifest, Extension
Subtags Reason, Url
Content Format Complex
Support
Definition

The <Support> tag encapsulates the set of URLs that will be used to provide support for the application administrators and users.

Subtags Link
Content Format Container
Triggers
Definition

The <Triggers> tag supplies the name of another element that is executed in response to the current element. For example, it can tell which Gmail contextual gadget is triggered when a given content extractor finds matching text in an email.

Example <Triggers ref="myContextualGadget"/>
Attributes
Name Format Description
ref Text The name of the element to be triggered. Must match an id defined in the same manifest.
Subtag of Extension
Content Format Complex
Url
Definition

The <Url> tag defines a URL in an extension. URLs can be specified as templates to included information about the domain that installed the application. Variables can be inserted using the syntax ${variable_name}, but currently only ${DOMAIN_NAME} is supported.

Example <Url>http://www.example.com/home.php?from=google&amp;domain=${DOMAIN_NAME}</Url>
Subtag of Extension, Scope
Content Format String
VerifiedSite
Definition

The <VerifiedSite> tag supplies a URL of a website owned by the developer of the application. The user logged-in when the manifest is uploaded must be registered owner of that website, or the manifest upload will fail. This website will be used to give users a verified identity of the developer of the application. Websites can be verified by visiting Google Webmaster Tools.

Example <VerifiedSite>http://www.example.com</VerifiedSite>
Subtag of ApplicationManifest
Content Format String

Supported Scopes

The following table lists the feeds that support 2-legged OAuth and may be accessed by applications if declared in the application manifest.

Google API Scope
Calendar Data API https://www.google.com/calendar/feeds/
Calendar Resource API (read only, Google Apps for Business only) https://apps-apis.google.com/a/feeds/calendar/resource/#readonly
Contacts Data API https://www.google.com/m8/feeds/
Documents List Data API https://docs.google.com/feeds/
Download PDFs and arbitrary files from Docs (read only) https://docs.googleusercontent.com/feeds/download/
Finance Data API https://www.google.com/finance/feeds/
Gmail Inbox Feed https://mail.google.com/mail/feed/atom/
Gmail IMAP/SMTP Access https://mail.google.com/
Provisioning API (read only)
  • https://apps-apis.google.com/a/feeds/user/#readonly
  • https://apps-apis.google.com/a/feeds/group/#readonly
  • https://apps-apis.google.com/a/feeds/nickname/#readonly
  • https://apps-apis.google.com/a/feeds/policies/#readonly

You can verify access has been granted by looking at the Manage OAuth Clients setting page in the control panel at http://www.google.com/a/{domain}/ManageOauthClients.

Sites Data API https://sites.google.com/feeds/
Spreadsheets Data API https://spreadsheets.google.com/feeds/

The following table shows the values allowed in the <Scope> tag in the manifest for a Gmail contextual gadget. These scopes define what parts of email messages may be accessed by the contextual gadget's content extractor.

Scope URIDescription
tag:google.com,2010:auth/contextual/extractor/SUBJECT Subject: line, stripped of any annotations added by the email client, such as Re: and Fwd:
tag:google.com,2010:auth/contextual/extractor/RAW_SUBJECT Subject: line, including all annotations added by the email client, such as Re: and Fwd:
tag:google.com,2010:auth/contextual/extractor/BODY Message body
tag:google.com,2010:auth/contextual/extractor/MESSAGE_ID Unique identifier that matches the Gmail frontend message id of the message (this is a 64-bit hexadecimal value, different from the RFC 822 Message-ID)
tag:google.com,2010:auth/contextual/extractor/TO_ADDRESS Email addresses of recipients specified in the To: line
tag:google.com,2010:auth/contextual/extractor/TO_PERSONAL Names of recipients specified in the To: line (actual user names, such as John Smith)
tag:google.com,2010:auth/contextual/extractor/FROM_ADDRESS Sender's email address
tag:google.com,2010:auth/contextual/extractor/FROM_PERSONAL Sender's name (actual user name, such as Vijay Agarwal)
tag:google.com,2010:auth/contextual/extractor/CC_EMAIL Email addresses of recipients specified in the CC: line
tag:google.com,2010:auth/contextual/extractor/CC_PERSONAL Names of recipients specified in the CC: line (actual user names, such as Melissa Waterston)
tag:google.com,2010:auth/contextual/extractor/BCC_EMAIL Email addresses of recipients specified in the BCC: line
tag:google.com,2010:auth/contextual/extractor/BCC_PERSONAL Names of recipients specified in the BCC: line (actual user names, such as Yuan Li)
tag:google.com,2010:auth/contextual/extractor/LIST_ID Mailing list
tag:google.com,2010:auth/contextual/extractor/LIST_UNSUBSCRIBE Mailing list unsubscribe link and email address
tag:google.com,2010:auth/contextual/extractor/DATE_SENT Timestamp when the email was sent
tag:google.com,2010:auth/contextual/extractor/DATE_RECEIVED Timestamp when the email was received

Getting Access to Additional Data

If an application implements a new feature that needs access to additional data, the developer only needs to define the required additional scopes in the application manifest. The domain administrator of each domain that has previously installed the application will be prompted to grant additional access in the Google Apps Control Panel (http://www.google.com/a/<domain>).

Applications that need additional data access will display the prompt "Update data access requirements" in the control panel UI. Domain administrators may then click "View and grant access", where they will be shown the additional scopes that are requested. If access to these scopes is approved, the application may then request access to that data.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.