# Amplitude Destination Config Reference


> Complete Rudder CLI reference for the Amplitude destination config keys, cloud mode settings, web and mobile SDK settings, auto-capture, and secrets.



[Amplitude](https://www.rudderstack.com/docs/destinations/streaming-destinations/amplitude/setup-guide/) is a product analytics destination. RudderStack sends events to Amplitude's HTTP API from its servers, or loads Amplitude's own SDKs in device mode on web, Android, iOS, React Native, and Flutter.

In an Amplitude destination spec:

- `type: am`
- `definition_version: 1`

## Sample configuration

```yaml
version: rudder/v1
kind: destination
metadata:
  name: amplitude-prod
spec:
  id: amplitude-prod
  display_name: Amplitude Production
  type: am
  definition_version: 1
  enabled: true
  config:
    api_key: "{{ .AMPLITUDE_API_KEY }}"
    api_secret: "{{ .AMPLITUDE_SECRET_KEY }}"
    residency_server: standard

    track_all_pages: false
    track_categorized_pages: true
    track_named_pages: true

    group_type_trait: company_type
    group_value_trait: company_name
    traits_to_set_once:
      - signup_date
    traits_to_increment:
      - login_count

    track_products_once: false
    track_revenue_per_product: true

    sdk_version:
      web: 2
    attribution:
      web: false
    track_session_events:
      web: true
      ios: true
    auto_capture:
      page_views:
        web: false
      web_vitals:
        web: true
    event_upload_threshold:
      web: "30"
      ios: "30"

    connection_mode:
      web: device
      ios: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - analytics
```

The above example loads Amplitude's SDKs on web and iOS in `device` mode, with web on SDK version 2 — which is what `auto_capture` and web `track_session_events` need. See [Web SDK](#web-sdk).

## Config keys

`config` accepts only the keys listed below. The [shared config key rules](https://www.rudderstack.com/docs/rudder-cli/destination-types/#config-key-rules) cover unknown keys, defaults, and immutability.

**Info**

Most Amplitude keys affect only one connection mode, or one platform's SDK. The groups below say which. Rudder CLI accepts every key whatever the mode — a key for the other mode is stored and ignored.

In `cloud` mode Amplitude accepts `alias`, `group`, `identify`, `page`, `screen`, and `track`. In `device` mode, web sources send `identify`, `track`, `page`, and `group`; mobile sources send `identify`, `track`, and `screen`.

### Connection

<div class="rs-ckeys">
<div class="rs-ckey" id="api_key">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">api_key</p>RequiredSecret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  API key of your Amplitude project, from the project&rsquo;s <strong>General</strong> tab.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="residency_server">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">residency_server</p>Required</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Amplitude data center RudderStack sends to.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>standard</code> (US) or <code>EU</code>.</li>
<li>The dashboard defaults this field to <code>standard</code>. Rudder CLI requires it explicitly.</li>
<li>A spec that omits this key fails validation.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="api_secret">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">api_secret</p>Secret</div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Secret key of your Amplitude project. RudderStack needs it to delete users, for example for GDPR requests. The dashboard calls it <strong>Secret key</strong>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, and must not contain line breaks.</li>
<li>A <code>{{ path || fallback }}</code> template is accepted in place of a literal.</li>
</ul>

</div>

</div>

</div>

### Page and screen events

`track_all_pages`, `track_categorized_pages`, and `track_named_pages` apply in `device` mode. On mobile they act on `screen` events rather than `page` events. Turning on more than one can send several Amplitude events for a single call. The custom name keys apply in `cloud` mode.

<div class="rs-ckeys">
<div class="rs-ckey" id="track_all_pages">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_all_pages</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send every <code>page</code> call to Amplitude as a <code>Loaded a Page</code> event.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to sources connected in <code>device</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="track_categorized_pages">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_categorized_pages</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send an event for each <code>page</code> call that has a category.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to sources connected in <code>device</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="track_named_pages">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_named_pages</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>true</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send an event for each <code>page</code> call that has a name.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to sources connected in <code>device</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="use_user_defined_page_event_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">use_user_defined_page_event_name</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Name <code>page</code> events from <code>user_provided_page_event_string</code> instead of the default name.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to events sent in <code>cloud</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="user_provided_page_event_string">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">user_provided_page_event_string</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Format for <code>page</code> event names. Each <code>{{ field }}</code> is replaced with that field from the event payload — for example <code>Viewed {{ name }} page</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>use_user_defined_page_event_name</code> is <code>true</code>. Leave it unset otherwise.</li>
<li>At most 200 characters, and must not contain line breaks.</li>
<li><code>{{ field }}</code>-style fields have no leading dot, so Rudder CLI&rsquo;s variable substitution leaves them alone.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="use_user_defined_screen_event_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">use_user_defined_screen_event_name</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Name <code>screen</code> events from <code>user_provided_screen_event_string</code> instead of the default name.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to events sent in <code>cloud</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="user_provided_screen_event_string">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">user_provided_screen_event_string</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Format for <code>screen</code> event names, on the same terms as <code>user_provided_page_event_string</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>use_user_defined_screen_event_name</code> is <code>true</code>. Leave it unset otherwise.</li>
<li>At most 200 characters, and must not contain line breaks.</li>
</ul>

</div>

</div>

</div>

### Identify and group traits

The trait lists take arrays of trait names, each at most 100 characters or a `{{ path || fallback }}` template.

<div class="rs-ckeys">
<div class="rs-ckey" id="group_type_trait">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">group_type_trait</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Trait whose value becomes the Amplitude <code>group_type</code> in <code>group</code> calls — for example a trait holding <code>industry</code>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, or a template.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="group_value_trait">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">group_value_trait</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Trait whose value becomes the Amplitude <code>group_value</code> in <code>group</code> calls — for example <code>retail</code> for the <code>industry</code> type.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>At most 100 characters, or a template.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="traits_to_increment">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">traits_to_increment</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>array of strings</code>
  </p>
<p class="rs-ckey__field">
  Description:
  <code>identify</code> traits Amplitude increments by their numeric value instead of overwriting.
</p>

</div>

<div class="rs-ckey" id="traits_to_set_once">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">traits_to_set_once</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>array of strings</code>
  </p>
<p class="rs-ckey__field">
  Description:
  <code>identify</code> traits Amplitude sets once and never overwrites.
</p>

</div>

<div class="rs-ckey" id="traits_to_append">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">traits_to_append</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>array of strings</code>
  </p>
<p class="rs-ckey__field">
  Description:
  <code>identify</code> traits whose values are appended to a list user property.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to <code>cloud</code> mode and to mobile sources in <code>device</code> mode — not to web device mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="traits_to_prepend">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">traits_to_prepend</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>array of strings</code>
  </p>
<p class="rs-ckey__field">
  Description:
  <code>identify</code> traits whose values are prepended to a list user property.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to <code>cloud</code> mode and to mobile sources in <code>device</code> mode — not to web device mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="enable_enhanced_user_operations">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">enable_enhanced_user_operations</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Enable Amplitude&rsquo;s enhanced user property operations.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies to <code>cloud</code> mode.</li>
<li>The dashboard shows this setting only to workspaces with the feature turned on.</li>
</ul>

</div>

</div>

</div>

### Ecommerce

<div class="rs-ckeys">
<div class="rs-ckey" id="track_products_once">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_products_once</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send an event carrying a <code>products</code> array as one event, with the products as properties, instead of one event per product.
</p>

</div>

<div class="rs-ckey" id="track_revenue_per_product">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_revenue_per_product</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Track each product&rsquo;s revenue individually. When <code>false</code>, the event carries the aggregate revenue of all products.
</p>

</div>

</div>

### Web SDK

These keys configure Amplitude's web SDK, so they apply only when `connection_mode.web` is `device`. Each object is keyed by `web`.

**Warning:** Several of these apply only to one web SDK version, set by `sdk_version.web`. `auto_capture` and `track_session_events.web` need version `2`; `track_new_campaigns` needs version `1`. A key for the other version is accepted and has no effect.

<div class="rs-ckeys">
<div class="rs-ckey" id="sdk_version">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">sdk_version</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Version of Amplitude&rsquo;s web SDK RudderStack loads. Review the <a href="https://www.rudderstack.com/docs/destinations/streaming-destinations/amplitude/device-mode/#behavior-changes-in-version-2" >behavior changes in version 2</a> before switching an existing destination.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — <code>1</code> or <code>2</code>, written as a number, not a string.</li>
<li>Rudder CLI fills in <code>2</code> only when the <code>sdk_version</code> block is present. Omit the block and no version is sent, so write it out.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">sdk_version:
  web: 2</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="proxy_server_url">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">proxy_server_url</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  <a href="https://www.docs.developers.amplitude.com/analytics/domain-proxy/" >Domain proxy</a> that relays the SDK&rsquo;s requests to Amplitude.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — string. Must not start with <code>http://</code> and must not contain <code>.ngrok.io</code>. A template is accepted.</li>
<li>The proxy must use HTTPS. Otherwise the proxy is ignored and data goes to Amplitude directly.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="version_name">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">version_name</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>string</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Version name sent to Amplitude with each event, for more detailed analysis.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>connection_mode.web</code> is <code>device</code>.</li>
<li>At most 100 characters, or a template.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="prefer_anonymous_id_for_device_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">prefer_anonymous_id_for_device_id</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Use the RudderStack anonymous ID as Amplitude&rsquo;s device ID instead of the SDK&rsquo;s own.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — boolean.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="attribution">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">attribution</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  <strong>Disables</strong> attribution tracking. <code>true</code> turns attribution off: GCLID, UTM parameters, and referrer aren&rsquo;t tracked. The dashboard calls this <strong>Disable Attribution</strong>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code> — boolean.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <strong>Warning:</strong> Despite its name, <code>attribution: {web: true}</code> switches attribution <strong>off</strong>. To keep attribution, leave it <code>false</code> or unset.
</div>

</div>

<div class="rs-ckey" id="track_new_campaigns">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_new_campaigns</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Save the referrer, URL parameters, and GCLID only <strong>once per session</strong>, ignoring new values that arrive later in the session. The dashboard calls this <strong>Save Referrer, URL Params, GCLID only once per session</strong> — it doesn&rsquo;t track new campaigns, whatever the name suggests.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>sdk_version.web</code> is <code>1</code>. Leave it unset otherwise.</li>
<li><code>web</code> — boolean. The dashboard defaults it to <code>true</code>; Rudder CLI doesn&rsquo;t fill it in.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="auto_capture">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">auto_capture</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Interactions Amplitude&rsquo;s web SDK captures on its own. Each setting is an object keyed by <code>web</code>, with a boolean value that defaults to <code>false</code> when the setting is present.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>Applies when <code>sdk_version.web</code> is <code>2</code>. Leave it unset otherwise.</li>
<li><code>page_views</code> — emit <code>[Amplitude] Page Viewed</code> on navigation, in addition to RudderStack&rsquo;s <code>page</code> calls. Leave off if you already send <code>page</code> calls on navigation, or page views are counted twice.</li>
<li><code>page_url_enrichment</code> — attach the current page URL to every event.</li>
<li><code>web_vitals</code> — capture Core Web Vitals (LCP, FCP, INP, CLS, TTFB).</li>
<li><code>file_downloads</code> — capture clicks on download links.</li>
<li><code>frustration_interactions</code> — capture rage clicks, dead clicks, and error clicks.</li>
<li><code>network_tracking</code> — capture failed network requests.</li>
<li><code>element_interactions</code> — capture clicks and changes on every element. High volume, and can capture user-entered text.</li>
<li><code>form_interactions</code> — capture form submissions and field changes, including field values that may be PII.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">auto_capture:
  web_vitals:
    web: true
  file_downloads:
    web: true</code></pre></div>
</div>
</div>

</div>

</div>

### Mobile SDK

These keys configure Amplitude's mobile SDKs, so they apply only to mobile sources connected in `device` mode. Each is an object keyed by the source types listed, with a boolean value.

<div class="rs-ckeys">
<div class="rs-ckey" id="map_device_brand">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">map_device_brand</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>boolean</code>
  </p><p class="rs-ckey__field">
    Default value:
    <code>false</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send the device brand to Amplitude.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>A plain boolean, not keyed by source type. Applies to <code>android</code>, <code>ios</code>, <code>react_native</code>, and <code>flutter</code> in <code>device</code> mode.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="enable_location_listening">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">enable_location_listening</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Capture location for users who&rsquo;ve granted the app location permission.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>android</code>, <code>react_native</code>, <code>flutter</code> — booleans. The dashboard defaults them to <code>true</code>; Rudder CLI doesn&rsquo;t fill them in.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="use_advertising_id_for_device_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">use_advertising_id_for_device_id</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send the Android Advertising ID as Amplitude&rsquo;s device ID.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>android</code>, <code>react_native</code>, <code>flutter</code> — booleans.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="use_idfa_as_device_id">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">use_idfa_as_device_id</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send the iOS IDFA as Amplitude&rsquo;s device ID.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>ios</code>, <code>react_native</code>, <code>flutter</code> — booleans.</li>
</ul>

</div>

</div>

</div>

### Batching and sessions

These keys apply to both web and mobile SDKs, so they take effect for any source connected in `device` mode. Each is keyed by source type.

<div class="rs-ckeys">
<div class="rs-ckey" id="event_upload_period_millis">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">event_upload_period_millis</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Time, in milliseconds, between the SDK&rsquo;s batch uploads.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code>, <code>android</code>, <code>ios</code>, <code>react_native</code>, <code>flutter</code> — digits only, written as a string: <code>&quot;1000&quot;</code>, not <code>1000</code>. At most 100 characters, or a template.</li>
<li>The dashboard defaults it to <code>&quot;1000&quot;</code>; Rudder CLI doesn&rsquo;t fill it in.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">event_upload_period_millis:
  web: &#34;1000&#34;
  android: &#34;5000&#34;</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="event_upload_threshold">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">event_upload_threshold</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Minimum number of events the SDK collects before uploading a batch.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>web</code>, <code>android</code>, <code>ios</code>, <code>react_native</code>, <code>flutter</code> — digits only, written as a string: <code>&quot;30&quot;</code>, not <code>30</code>. At most 100 characters, or a template.</li>
<li>The dashboard defaults it to <code>&quot;30&quot;</code>; Rudder CLI doesn&rsquo;t fill it in.</li>
</ul>

</div>

</div>

<div class="rs-ckey" id="track_session_events">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_session_events</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Send session start and end events.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>android</code>, <code>ios</code>, <code>react_native</code>, <code>flutter</code> — booleans.</li>
<li><code>web</code> — boolean, default <code>false</code> when the block is present. Applies only when <code>sdk_version.web</code> is <code>2</code>.</li>
</ul>

</div>

</div>

</div>

### Internal keys

The eight keys below are older Amplitude web SDK settings — the keys above are what configure today's integration. Rudder CLI accepts them so that a destination already carrying these values keeps them; without them in the spec, an update would drop whatever is stored. Leave them out of a new destination, and keep whatever `rudder-cli import` brings back.

Each is an object keyed by `web`, with a boolean value.

<div class="rs-ckeys">
<div class="rs-ckey" id="batch_events">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">batch_events</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Batches events in the browser before uploading them. <code>event_upload_period_millis</code> and <code>event_upload_threshold</code> are the keys the dashboard exposes for batching.
</p>

</div>

<div class="rs-ckey" id="device_id_from_url_param">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">device_id_from_url_param</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Sets the device ID from the <code>amp_device_id</code> URL parameter.
</p>

</div>

<div class="rs-ckey" id="force_https">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">force_https</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Always uploads over HTTPS, rather than following the embedding page&rsquo;s protocol.
</p>

</div>

<div class="rs-ckey" id="track_gclid">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_gclid</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Captures the <code>gclid</code> URL parameter alongside the user&rsquo;s <code>initial_gclid</code>. Attribution as a whole is controlled by <code>attribution</code>.
</p>

</div>

<div class="rs-ckey" id="track_referrer">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_referrer</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Captures <code>referrer</code> and <code>referring_domain</code> for each session, alongside the user&rsquo;s initial values.
</p>

</div>

<div class="rs-ckey" id="track_utm_properties">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">track_utm_properties</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Parses UTM parameters from the query string or <code>_utmz</code> cookie and sends them as user properties.
</p>

</div>

<div class="rs-ckey" id="save_params_referrer_once_per_session">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">save_params_referrer_once_per_session</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Captures GCLID, referrer, and UTM parameters once per session. On web SDK version 1, <code>track_new_campaigns</code> is the key the dashboard exposes for this.
</p>

</div>

<div class="rs-ckey" id="unset_params_referrer_on_new_session">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">unset_params_referrer_on_new_session</p>Internal</div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Resets <code>referrer</code> and UTM properties to null at the start of each session, instead of carrying the previous values forward.
</p>

</div>

</div>

### Event filtering

**Warning:** [Client-side event filtering](https://www.rudderstack.com/docs/sources/event-streams/sdks/event-filtering/) applies only to sources connected in `device` mode — the dashboard shows these controls only then, and the SDK is what applies the filter. Rudder CLI accepts the block in any mode, but it has no effect on cloud-mode events.

<div class="rs-ckeys">
<div class="rs-ckey" id="event_filtering">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">event_filtering</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Restricts which <code>track</code> events the SDK passes to Amplitude, by event name.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li><code>whitelist</code> — array of event names to allow; every other <code>track</code> event is dropped.</li>
<li><code>blacklist</code> — array of event names to drop; every other <code>track</code> event is allowed.</li>
<li>The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.</li>
<li>Each name is at most 100 characters, or a <code>{{ path || fallback }}</code> template.</li>
</ul>

</div>

</div>

</div>

### Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under [Source types](#source-types). A key naming a source type this destination doesn't support fails validation.

<div class="rs-ckeys">
<div class="rs-ckey" id="connection_mode">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">connection_mode</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Maps each source type you connect to the mode its events reach Amplitude in, using the modes in <a href="#source-types" >Source types</a>.
</p>

<div class="rs-ckey__notes">
  <p class="rs-ckey__field">Notes:</p>
  <ul>
<li>An entry is required for each source type you connect — see <a href="#connect-a-source" >Connect a source</a>.</li>
<li>A mode the source type doesn&rsquo;t support on this destination fails validation — for example <code>device</code> for <code>ios_swift</code>.</li>
</ul>

</div>

<div class="rs-ckey__extra">
  <div class="rs-code">
  <div class="rs-code__head">yaml<button class="rs-code__copy" type="button">
      
      Copy
    </button>
  </div>
  <div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml">connection_mode:
  web: device
  ios: device
  android_kotlin: cloud</code></pre></div>
</div>
</div>

</div>

<div class="rs-ckey" id="consent_management">
  <div class="rs-ckey__title">
    <p class="rs-ckey__name">consent_management</p></div>
  <p class="rs-ckey__field">
    Type:
    <code>object</code>
  </p>
<p class="rs-ckey__field">
  Description:
  Consent provider configuration per source type. The entry shape, accepted providers, and the rules on <code>resolution_strategy</code> and <code>consents</code> are shared across all destination types — see <a href="https://www.rudderstack.com/docs/rudder-cli/destination-types/#consent-management" >Consent management</a>.
</p>

</div>

</div>

## Source types

Amplitude accepts events from these source types in the mentioned connection modes:

| Source type | Connection mode |
| :-----| :-----|
| `android` | `cloud`, `device` |
| `android_kotlin` | `cloud` |
| `ios` | `cloud`, `device` |
| `ios_swift` | `cloud` |
| `web` | `cloud`, `device` |
| `unity` | `cloud` |
| `cloud` | `cloud` |
| `react_native` | `cloud`, `device` |
| `flutter` | `cloud`, `device` |
| `cordova` | `cloud` |
| `warehouse` | `cloud` |

`web`, `android`, `ios`, `react_native`, and `flutter` offer `device` mode. The Kotlin and Swift SDKs — `android_kotlin` and `ios_swift` — are `cloud` only. See [Amplitude device mode](https://www.rudderstack.com/docs/destinations/streaming-destinations/amplitude/device-mode/).

`warehouse` is the token a [Reverse ETL source](https://www.rudderstack.com/docs/sources/reverse-etl/) resolves to. Rudder CLI manages the destination’s `warehouse` entry — if the destination is connected to a Reverse ETL source, set `connection_mode.warehouse: cloud` in its spec, or `apply` removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under [Supported destinations](https://www.rudderstack.com/docs/rudder-cli/yaml-retl-connections/#supported-destinations) — see [Manage Reverse ETL Connections using Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/retl-connections/).

**Info:** The dashboard additionally offers Amplitude to AMP and Shopify sources. Rudder CLI doesn&#39;t manage those connections, so `amp` and `shopify` are invalid here.

## Connect a source

An event stream connection to this destination is checked against two rules at `validate` time.

**The source's type must be supported.** A source's type resolves to one of the tokens above before the check — a JavaScript source resolves to `web`, and webhook and server-side SDK sources resolve to `cloud`. Every type an event stream source can resolve to is supported here, so this check always passes.

**The destination config must carry a `connection_mode` entry for that source type.** This lives on the destination spec, not on the [connection spec](https://www.rudderstack.com/docs/rudder-cli/yaml-connections/). Without it:

```text
destination 'amplitude-prod' config has no 'connection_mode' entry for source type 'web'
```

Amplitude needs no additional config keys to connect a source of any type, in any mode.

## Secrets

`api_key` and `api_secret` are the secret keys. Write each as a `{{ .VAR }}` reference and supply the value at apply time:

```yaml
config:
  api_key: "{{ .AMPLITUDE_API_KEY }}"
  api_secret: "{{ .AMPLITUDE_SECRET_KEY }}"
```

```bash
export RUDDER_AMPLITUDE_API_KEY="..."
export RUDDER_AMPLITUDE_SECRET_KEY="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml
```

Note that:

- `rudder-cli import` writes only the secrets the API returns, as `{{ .VAR }}` references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see [Secrets](https://www.rudderstack.com/docs/rudder-cli/destination-types/#secrets).
- In device mode the API key is embedded in the app or page, so masking it protects your YAML, not the value itself. The secret key is used server-side, for user deletion.

See [How to Use Variable Substitution in Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/variable-substitution/).

## Changes by release

<table>
  <thead>
    <tr>
      <th>Version</th>
      <th>Change</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Breaking:</strong> A <code>null</code> config value, written as <code>key: null</code>, <code>key: ~</code>, or <code>key:</code> with no value, fails <code>validate</code> with <code>'&lt;key&gt;' must not be null; set a value or remove the key</code>. Earlier releases accepted it: a top-level null planned an update on every <code>apply</code>, and a null inside a list item failed at the API.<br><strong>What to do:</strong> Remove the key to leave it unset, or give it a value.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Breaking:</strong> An empty string, <code>&quot;&quot;</code>, on a key that takes one of a fixed set of values fails <code>validate</code> with <code>'&lt;key&gt;' must be one of [...]</code>, unless <code>&quot;&quot;</code> is one of the key&rsquo;s values. Earlier releases accepted it, and the API rejected it at <code>apply</code>.<br><strong>What to do:</strong> Remove the key to leave it unset, or set one of the listed values.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>validate</code> warns when a secret key holds anything but one <code>{{ .VAR }}</code> reference with no default, and when one variable fills two secret keys. It also masks secret values in the lines it prints.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>rudder-cli import</code> writes each secret reference single-quoted, as <code>'{{ .VAR }}'</code>, so a value containing double quotes, like a JSON key file, substitutes as a string. A single quote in a value that fills such a reference is written as <code>''</code>.<br><strong>What to do:</strong> In a spec imported by an earlier release, quote each reference to a JSON value by hand: <code>'{{ .VAR }}'</code>.</td>
    </tr>
    <tr>
      <td>v0.29.0</td>
      <td><strong>Changed:</strong> <code>validate</code> reports a value of the wrong type once per key, such as <code>'email' must be a string</code>, instead of one raw decoding error.</td>
    </tr>
    <tr>
      <td>v0.28.0</td>
      <td><strong>Added:</strong> <code>warehouse</code> source type, for destinations connected to a Reverse ETL source. Set <code>connection_mode.warehouse: cloud</code> for such a destination, or <code>apply</code> removes the entry.</td>
    </tr>
  </tbody>
</table>

For changes across every destination type, see [Destination Type Changes by Release](https://www.rudderstack.com/docs/rudder-cli/destination-types/changes/).

## See more

- [Amplitude Destination](https://www.rudderstack.com/docs/destinations/streaming-destinations/amplitude/setup-guide/) for the full setting reference per mode and platform
- [Destination Type Reference for Rudder CLI](https://www.rudderstack.com/docs/rudder-cli/destination-types/) for the rules shared across destination types
- [Destination YAML Reference](https://www.rudderstack.com/docs/rudder-cli/yaml-destinations/) for the spec envelope