app.yml

5 min

Define your app in the app.yml file, including store details, runtime, functions, and jobs that your app uses.

meta section of app.yml

The meta section of the app.yml file describes the basic elements of your app. It includes the following fields:

app_id – The unique identifier of your application in Connect Platform for Optimizely Data Platform (ODP).

display_name – The name that displays for your app in the ODP App Directory.

version – The version of your app that displays in the ODP App Directory.

vendor – The display name of your firm or company that displays in the ODP App Directory.

summary – The description of your app that displays in the ODP App Directory.

support_url – The support URL for your app or company that displays in the ODP App Directory.

contact_email – The email customers contact for questions or issues with your app.

categories – Tag the app for sorting in the ODP App Directory. See the options below:

Advertising

Channel

Commerce Platform

Content Management

Lead Capture

Loyalty & Rewards

Marketing

Merchandising & Products

Offers

Productivity

Reviews & Ratings

Site & Content Experience

Subscriptions

Surveys & Feedback

availability – The global regions where you want to make the app available. See the options below:

us – United States (required)

eu – Europe

au – Asia-Pacific

all – All current and future available deployment regions.

Below is an example of the meta section of the app.yml file for a data integration app between (ODP and Klaviyo.

meta:
  app_id: klaviyo_collect
  display_name: Klaviyo Collect
  version: 0.1.1
  vendor: Zaius
  summary: Collect Data from Klaviyo
  support_url: https://www.optimizely.com
  contact_email: [email protected]
  categories:
    - Marketing
  availabiity:
   - us

The following image shows how this example app displays in the ODP App Directory:

And how it displays when users select the app in the ODP App Directory.

Complete app.yml file example

Below is a complete example of an app.yml file:

meta:
  app_id: sample_app
  display_name: Sample App
  version: 1.0.0
  vendor: optimizely
  summary: A sample app
  support_url: https://www.optimizely.com
  contact_email: [email protected]
  legal_url: https://optimizely.com/privacy_policy
  categories:
    - Commerce Platform
  availabiity:
   - all

runtime: node22

environment:
  - APP_ENV_GLOBAL_SECRET

functions:
  handle_event:
    entry_point: HandleEvent
    description: Transforms incoming data into ODP events

jobs:
  historical_import:
    entry_point: HistoricalImport
    description: Performs a one-time historical import when triggered

  nightly_import:
    entry_point: NightlyImport
    # runs at midnight every night
    cron: 0 0 0 ? * *
    description: Performs a nightly import for data that isn't provided or needed in real-time
    
liquid_extensions:
  generate_coupon:
    entry_point: GenerateCoupon
    description: Generates a unique coupon code
    input:
      rule:
        type: string
        required: true
        description: The coupon rule to create the coupon from
      email:
        type: string
        required: false
        description: Email address to tie the coupon code to
        
channel:
  type: facebook_messenger
  targeting:
    - identifier: sample_app_messenger_id
  options:
    prepare: true

Example data integration

This example app pulls data from an email service provider (ESP). The import job can handle both the historical import and hourly pulls. The GetEspLists function lets you pull lists from the ESP so you can import them.

meta:
  app_id: esp_collect
  display_name: ESP Collection App
  version: 1.0.0
  vendor: optimizely
  summary: An app that imports contacts and activity
  support_url: https://www.optimizely.com
  support_email: [email protected]
  categories:
    - Marketing Automation

runtime: node22

functions:
  get_esp_lists:
    entry_point: GetEspLists
    description: Pulls the lists from the ESP to select which ones you want imported

jobs:
  import:
    entry_point: Import
    description: Performs a one-time historical import when triggered
    # Runs every hour
    cron: 0 0 * * * ?

Example channel integration

This app integrates with an SMS vendor to send text messages. It has the SmsCallbackHandler, which gets the webhook activity that comes from the vendor. It also includes details about the SMS channel, defines how the app handles reachability and defines the supported identifiers.

meta:
  app_id: sms
  display_name: SMS
  version: 1.0.0
  vendor: optimizely
  summary: Deliver transactional and promotional messages over SMS from any ODP campaign
  support_url: https://apps.optimizely.com/sms
  contact_email: [email protected]
  categories:
    - Channel

runtime: node22

functions:
  sms_callback:
    entry_point: SmsCallbackHandler
    description: Handles incoming messages and events about message delivery

channel:
  type: sms
  targeting:
    - identifier: phone
  options:
    prepare: false
  metrics:
    delivery:
      - sent
      - delivery
      - delivery_unknown
    reachability:
      - hard_bounce
      - soft_bounce