Template Operations¶

The process for creating or updating a template via the python library consists of 3 steps:

Add/remove/set template headers
Add/remove/set template metadata
Add/remove/set template fields

This tutorial explains the relevant classes, methods, and enums for accomplishing the above tasks. In the code samples throughout the tutorial, we assume that the following imports/constants are defined:

import uareach as ua

client = ua.Reach('you@example.com', 'reach-key')

# Initialize the template -- in this example, we create an apple template.
my_template = ua.AppleTemplate()

Metadata¶

When manipulating a template, you’ll use the one of the following methods to update the template metadata:

# Add metadata to the template
my_template.add_metadata(name='A template')

# Remove metadata from the template
my_template.remove_metadata('name')

# Set the template metadata (remove all currently existing metadata, and
# add the specified key/values)
my_template.set_metadata(name='A template', description='Template description')

The table below contains a full listing of available keys for the metadata methods:

Key	Description	Required
`name`	The name of the template.	Yes
`vendor`	One of `'apple'` or `'google'`. Set automatically by the library.	Yes (set automatically)
`vendorId`	One of `1` or `2`. Set automatically by the library.	Yes (set automatically)
`project_type`	The type of the project. See template_type for options.	Yes (alternatively can use `type_`)
`template_type`	The type of the template. See project_type for options.	Yes (alternatively can use `type_`)
`type_`	Helper key – allows you to set project_type and template_type simultaneously. See type for details.	No
`deleted`	A boolean representing whether the template is deleted.	No
`description`	A description for the template.	No
`disabled`	A boolean representing whether the template is disabled.	No
`template_id`	The template ID.	No
`project_id`	The ID of the project associated with the template.	No

Note

You will either specify both project_type and template_type, or you can use the streamlined type_ key which takes care of setting the two former keys for you.

Note

When using the remove_metadata method, you must pass in the Key values as strings (e.g., 'name', 'description', etc).

template_type¶

The table below lists possible values for the template_type key. You can use either the provided constant or the associated string:

Constant	Associated String
`TemplateType.BOARDING_PASS`	`'Boarding Pass'`
`TemplateType.COUPON`	`'Coupon'`
`TemplateType.EVENT_TICKET`	`'Event Ticket'`
`TemplateType.GENERIC`	`'Generic'`
`TemplateType.STORE_CARD`	`'Store Card'`
`TemplateType.LOYALTY`	`'Loyalty'`
`TemplateType.OFFER`	`'Offer'`
`TemplateType.GIFT_CARD`	`'Gift Card'`

project_type¶

The table below lists possible values for the project_type key. You can use either the provided constant or the associated string:

Constant	Associated String
`ProjectType.BOARDING_PASS`	`'boardingPass'`
`ProjectType.COUPON`	`'coupon'`
`ProjectType.EVENT_TICKET`	`'eventTicket'`
`ProjectType.GENERIC`	`'generic'`
`ProjectType.LOYALTY`	`'loyalty'`
`ProjectType.GIFT_CARD`	`'giftCard'`
`ProjectType.MEMBER_CARD`	`'MemberCard'`

type¶

The type_ key provides an alternative to setting both project_type and template_type. You can choose from one of the options listed below:

Type Constant
`Type.LOYALTY`
`Type.COUPON`
`Type.GIFT_CARD`
`Type.MEMBER_CARD`
`Type.EVENT_TICKET`
`Type.BOARDING_PASS`
`Type.GENERIC`

Headers¶

Template headers specify high-level template options – associated images, template colors, and barcode options are all specified via headers. Available operations on template headers mirror those available for metadata:

# Add headers to the template
apple_coupon.add_headers(
    barcode_type='BarcodeFormatPDF417',
    logo_image='https://s3.amazonaws.com/passtools_prod/1/images/default-pass-logo.png',
    background_color=ua.rgb(0, 147, 201),
    logo_color=ua.rgb(24, 86, 148),
    foreground_color=ua.rgb(255, 255, 255),
)

# Remove headers from the template
my_template.remove_headers('logo_image')

# Set the template headers (remove all currently existing metadata, and
# add the specified key/values)
my_template.set_headers(
    background_color=ua.rgb(0, 147, 201),
    logo_color=ua.rgb(24, 86, 148),
    foreground_color=ua.rgb(255, 255, 255)
)

See below for a complete listing of available headers:

Key	Description
`background_color`	The background color of the template.
`background_image`	The background image of the template.
`barcodeAltText`	The text that displays below the barcode.
`barcode_encoding`	The barcode encoding type. Use `'iso-8859-1'`
`barcode_type`	The barcode type. See barcode_type for available options.
`barcode_value`	The actual value represented by the barcode.
`footer_image`	Link to image to display in the template footer.
`foreground_color`	Specify the template foreground color.
`icon_image`	Specify the template icon image.
`logo_color`	Specify the template logo color (Apple only).
`logo_image`	Specify the template logo image.
`logo_text`	Specify the text under the template logo.
`strip_image`	Specify the barcode strip image.
`suppress_strip_shine`	A boolean – Suppress the strip shine effect on barcodes.
`thumbnail_image`	A URL specifying the thumbnail image.
`transitType`	Only used with boarding pass. See transitType (Apple Only) for available options.

barcode_type¶

See below for a full listing of barcode_type values. Note that some barcode types are only available for Google templates.

Constant	Associated String	Apple	Google
`BarcodeType.PDF_417`	`'PDF_417'`	Yes	Yes
`BarcodeType.AZTEC`	`'AZTEC'`	Yes	Yes
`BarcodeType.QR_CODE`	`'QR_CODE'`	Yes	Yes
`BarcodeType.CODE_128`	`'CODE_128'`	Yes	Yes
`BarcodeType.UPC_A`	`'UPC_A'`	No	Yes
`BarcodeType.EAN_13`	`'EAN_13'`	No	Yes
`BarcodeType.CODE_39`	`'CODE_39'`	No	Yes

transitType (Apple Only)¶

Transit type is used to specify the type of transportation on an on Apple Boarding Pass. See below for a full listing of transitType values:

Constant	Associated String
`TransitType.GENERIC`	`'transitTypeGeneric'`
`TransitType.BUS`	`'transitTypeBus'`
`TransitType.AIR`	`'transitTypeAir'`
`TransitType.BOAT`	`'transitTypeBoat'`
`TransitType.TRAIN`	`'transitTypeTrain'`

Fields¶

The Python Library uses a single field class for both Apple and Google templates.

The Field class is used to build fields. Let’s look at a simple example:

program_name = ua.Field(
    name='Program Name',
    label='Program Name',
    value='Loyalty Points',
    fieldType=ua.AppleFieldType.PRIMARY
)

Note that the only thing that distinguishes this as a field for an Apple Template is the fieldType value. Aside from a handful of Google and Apple-specific keys, Apple and Google field definitions will usually look similar. Here is a roughly analagous field definition for a Google field:

loyalty_program = ua.Field(
    name='Program Name',
    label='Program Name',
    value='Loyalty Points',
    fieldType=ua.GoogleFieldType.TITLE_MODULE
)

Here is a complete listing of valid keys for Field:

Key	Value Type	Apple/Google	Description	Additional Notes
`name`	String	Both	The name used to refer to the field.
`label`	String	Both	The label of the field – generally describes the field value.
`value`	String, Int, or Float	Both	The value of the field.
`fieldType`	String	Both	The location of the field on the template. See fieldTypes for options.
`changeMessage`	String	Both	The message to display if the field is updated.
`formatType`	String	Both	The type of value. See formatType for options.	The python library will attempt to determine this automatically
`hideEmpty`	Boolean	Both	Hide the field if no value is specified.
`order`	Int	Both	Specify location within the `fieldType`.
`required`	Boolean	Both	Whether the field must be defined when creating passes from the template.
`currencyCode`	String	Both	If making a field with a currency value, specify the denomination. See currencyCode for options.	If you set `currencyCode`, `formatType` will be set to `"Currency` unless you manually override
`textAlignment`	String	Both	Specify how text is aligned within the field. See textAlignment for options.
`numberStyle`	String	Apple	If `value` is a number, specify the number type. See numberStyle for options.	The python library will attempt to determine this automatically
`row`	Int	Google	Specify vertical location within the `fieldType`.	Deprecated, please use `order` if possible
`col`	Int	Google	Specify horizontal location within the `fieldType`.	Deprecated, please use `order` if possible

Note

While the formatType and numberStyle keys will be set automatically, you can always override them. The python library will do its best to guess and should be correct in most situations, but there may be edge cases where you have to override set these values explicitly.

formatType¶

The formatType key specifies the type of argument passed to value. Generally, the library can deduce the formatType without user intervention. However, 'Phone' and 'Email' will always have to be specified by the user.

Constant	Associated String
`FormatType.NUMBER`	`'Number'`
`FormatType.STRING`	`'String'`
`FormatType.URL`	`'URL'`
`FormatType.DATE`	`'Date'`
`FormatType.CURRENCY`	`'Currency'`
`FormatType.PHONE`	`'Phone'`
`FormatType.EMAIL`	`'Email'`

fieldTypes¶

The fieldType key specifies the location of a field on an Apple or Google template. The available fieldTypes are listed below:

Google fieldTypes:

Constant	Associated String
`GoogleFieldType.INFO_MODULE`	`'infoModuleData'`
`GoogleFieldType.TEXT_MODULE`	`'textModulesData'`
`GoogleFieldType.LINKS_MODULE`	`'linksModuleData'`
`GoogleFieldType.POINTS_MODULE`	`'pointsModule'`
`GoogleFieldType.NOT_ASSIGNED`	`'notAssigned'`
`GoogleFieldType.TITLE_MODULE`	`'titleModule'`
`GoogleFieldType.ACCOUNT_MODULE`	`'acctModule'`
`GoogleFieldType.LOYALTY_POINTS`	`'loyaltyPoints'`

Apple fieldTypes:

Constant	Associated String
`AppleFieldType.PRIMARY`	`'primary'`
`AppleFieldType.SECONDARY`	`'secondary'`
`AppleFieldType.TERTIARY`	`'tertiary'`
`AppleFieldType.AUXILIARY`	`'auxiliary'`
`AppleFieldType.BACK`	`'back'`
`AppleFieldType.HEADER`	`'header'`
`AppleFieldType.NOT_ASSIGNED`	`'notAssigned'`

numberStyle (Apple Only)¶

The numberStyle key must be specified for Apple fields with a formatType of 'Number'. Usually, the library can deduce the appropriate numberStyle based on the value argument, but there still may be situations where it is useful to manually override the numberStyle key.

Constant	Assocaited String
`NumberStyle.DECIMAL`	`'numberStyleDecimal'`
`NumberStyle.TEXT`	`'numberStyleSpellOut'`
`NumberStyle.SCIENTIFIC`	`'numberStyleScientific'`
`NumberStyle.PERCENT`	`'numberStylePercent'`

textAlignment¶

Specify the alignment of the field text:

Constant	Associated String
`TextAlignment.LEFT`	`'textAlignmentLeft'`
`TextAlignment.CENTER`	`'textAlignmentCenter'`
`TextAlignment.RIGHT`	`'textAlignmentRight'`
`TextAlignment.NATURAL`	`'textAlignmentNatural'`

currencyCode¶

Specify the type of currency for Currency fields:

Constant	Associated String
`CurrencyCode.USD`	`'USD'`
`CurrencyCode.EUR`	`'EUR'`
`CurrencyCode.CNY`	`'CNY'`
`CurrencyCode.JPY`	`'JPY'`
`CurrencyCode.GBP`	`'GBP'`
`CurrencyCode.RUB`	`'RUB'`
`CurrencyCode.AUD`	`'AUD'`
`CurrencyCode.CHF`	`'CHF'`
`CurrencyCode.CAD`	`'CAD'`
`CurrencyCode.HKD`	`'HKD'`
`CurrencyCode.SEK`	`'SEK'`
`CurrencyCode.NZD`	`'NZD'`
`CurrencyCode.KRW`	`'KRW'`
`CurrencyCode.SGD`	`'SGD'`
`CurrencyCode.NOK`	`'NOK'`
`CurrencyCode.MXN`	`'MXN'`
`CurrencyCode.INR`	`'INR'`

Apple Only Features¶

These methods are specific to the AppleTemplate class.

Beacons¶

To manipulate beacons on a template, use one of the following AppleTemplate methods:

# Add a beacon
my_template.add_beacon(
   '55502220-A123-A88A-F321-555A444B333C',      # UUID
   relevantText="Hey you're in a cool place",   # Text displayed on lock screen
   major=1,                                     # Major beacon identifier
   minor=34                                     # Minor beacon identifier
)

# Remove a beacon (takes a UUID as argument)
my_template.remove_beacon('55502220-A123-A88A-F321-555A444B333C')

Google Only Features¶

These methods are specific to the GoogleTemplate class.

Offer Module¶

When creating a Google coupon, you can specify an offerModule. To do so, use the set_offer method:

my_template.set_offer(
   multiUserOffer=False,
   redemptionChannel='both',
   provider='The provider',
   endTime='2017-01-30T00:00:00.000Z'
)

Valid arguments are listed below:

Key	Description
`multiUserOffer`	If true, this offer can be saved by multiple users. Otherwise, the offer is only available for a single user.
`redemptionChannel`	Redemption channels applicable to this offer. Can be one of `'online'`, `'instore'`, `'both'`, or `'temporaryPriceReduction'`.
`provider`	The provider name.
`endTime`	The offer expiration date.

Message Module Field¶

To add a message to your template, use the add_message method:

my_template.add_message(
    body='A new message!',
    imageUri='https://imgur.com/cool_image.png'
)

Valid arguments are listed below:

Key	Required	Description
`body`	Yes	The message body.
`header`	No	The message title.
`actionUri`	No	The URI to which users are directed upon clicking the message.
`actionUriDescription`	No	Description for the `actionUri`.
`imageUri`	No	Specify an image to display with the message.
`imageDescription`	No	Description for the image.
`startTime`	No	Valid ISO8805 date for start time of a message.
`endTime`	No	Valid ISO8805 date for end time of a message.