Migration map.

analytics_tools_apply

Update one or more analytics IDs in one partial save, verify preservation of the complete custom settings, then request recaching. All five providers are options of this tool.

Access and preconditions

Requires OWNER or DELEGATEE with MANAGE_ANALYTICS_TOOLS for the selected channel. The source-defined hosted selected-channel resource admits this tool only for its exact channelCode; the account resource excludes it and its analytics-tools recovery type. Source scoping is not deployed authorization evidence.

Read analytics_tools_get and retain its revision. A new plan independently reads the complete custom record and DNS observation twice and verifies channel/context continuity. expectedRevision covers unrelated business settings and timestamps as well as the five IDs; stale state returns ANALYTICS_CONFLICT before dispatch. Domain observation changes after preparation return ANALYTICS_DOMAIN_CHANGED and pause remaining writes.

The host configures CHANNEL_ENV, DNS and ROBO_FRIENDLY services. A new changed plan validates these services even with dryRun:true. An existing-record no-op skips recache-service validation, but still requires the design/DNS reads and current context. No active-domain or paid-plan prerequisite is imposed. Observed domains supply the recache header; DNS 404 retains explicit uncertainty and permits channel-only recaching. Do not supply service origins or credentials as tool inputs.

Inputs

The outer object and settings are strict. Supply at least one settings field. Omitted fields are preserved; an empty string clears a field. There is no separate provider tool or reset flag.

Each supplied ID is a string of at most 4,096 characters before normalization. Every JavaScript whitespace character is removed throughout all five fields, not just at the ends. A whitespace-only field therefore clears it. Google checks enforce only the prefix, not a complete provider ID format; the other three fields have no numeric-only check. Whitespace transformation, prefix checks, the at-least-one rule and safe channel segments are not fully represented in exported JSON Schema.

Input examples

These are illustrative plans. Replace the channel and zero-filled revision with a fresh reader result; use the user's intended IDs for a real change.

{
  "channelCode":"selected-channel-code",
  "requestId":"analytics-combined-plan-001",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "settings":{"gaTrackingId":"G-EXAMPLE","gtmId":"GTM-EXAMPLE","fbPixelId":"1234567890","kaPixelId":"2345678901","nvPreLogId":"example-log-id"},
  "dryRun":true
}

{
  "channelCode":"selected-channel-code",
  "requestId":"analytics-meta-plan-001",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "settings":{"fbPixelId":"1234567890"},
  "dryRun":true
}

{
  "channelCode":"selected-channel-code",
  "requestId":"analytics-clear-plan-001",
  "expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000",
  "settings":{"fbPixelId":""},
  "dryRun":true
}

Execution and preservation

A new dry run returns PLAN_READY with normalized requested settings, initializationRequired, changesRequired, recacheRequired and recacheDomain. It creates no task. With an existing identical task, dryRun validates identity/fingerprint/current authority and returns existingPhase; it does not reread the business state or return a fresh plan.

A real existing-record no-op creates a done journal but sends no initialization, save or recache. All acknowledgements are false. Otherwise the workflow checkpoints each dispatch before sending it:

1. Only after a verified custom-record 404, POST /seller/api/v1/channel-management/custom with an empty object, then read the newly observed full baseline. The adapter expects HTTP 200 without a response-body contract.
2. PUT /seller/api/v1/channel-management/custom/experimentals with only the normalized requested fields. The adapter expects HTTP 200 without a response-body contract. Readback must match all requested and omitted settings, including unknown recursive JSON business fields, plus the original record ID, channel ID and insertedAt. updatedAt may change during saving.
3. POST /seller/api/v1/recache to ROBO_FRIENDLY with an empty object and the channel header. Include the observed connected-domain header only when available. Credential/context drift still invalidates the result.
4. Recheck the complete saved snapshot, including updatedAt, and the original domain observation before marking done.

Only rotating top-level experimentals.id/exp_id are excluded from preservation; nested names remain protected. A malformed read is never replaced with defaults. Initialization, save and recache are separate requests with no transaction or automatic rollback. A recache failure can leave settings saved.

Results

ANALYTICS_COMPLETE includes phase done, settings and revision. Interpret initializationAcknowledged, settingsSaveAcknowledged, cacheRequestAcknowledged, settingsReadbackRecorded, writesPerformed and historical separately. Save acknowledgement is retained only after matching readback; reconciliation without an observed acknowledgement can advance with that flag false. writesPerformed is false for a no-op, true with an initialization/save acknowledgement, false at prepared, and otherwise null when causality is uncertain.

A fresh completion has verification.confirmed:true and settingsReadbackVerified:true. A no-op does not imply a cache request. Completed replay/status has historical:true and confirmed:false; use get for current settings. cacheFreshnessVerified, visitorTrackingVerified, providerOwnershipVerified, causalityVerified and atomicSnapshot remain false.

ANALYTICS_PENDING includes phase and lastResult. Once a saved snapshot exists it also exposes lastVerifiedSettings and lastVerifiedSettingsAreCurrent:false; this is a checkpoint, not a fresh observation. An uncertain recache supplies a human_console inspection action; other pending stages supply inspect_task. journalPersistence.saved:false means the error checkpoint could not be persisted. Authentication/context failures can suppress channel/console metadata. Preserve the original task in all these cases.

Task recovery

The journal binds requested ID, embedded ID, input requestId, normalized input fingerprint, revision, domain and selected channel/operator/credential context. Invalid identity, snapshots, phases or acknowledgements return TASK_STATE_UNVERIFIED. Changed normalized input under an existing ID returns REQUEST_ID_CONFLICT.

Status never advances work. Resume may send untouched stages. Even a definite HTTP failure does not reset a sent checkpoint. Do not create a new requestId merely to retry uncertain caching; inspect the returned console/backend and use get for current values.

Saved plan replay

For an existing matching task, dryRun returns historical saved plan/progress, with historical:true, replayed:true and false current verification. It performs no fresh business-state or eligibility check, no business effect and no journal change. Current console/action links are omitted. Follow nextStep for the same target's current state; keep the original task ID for uncertain-outcome recovery. Context and saved-input checks still apply. A new task follows normal fresh-plan validation; another request ID must not bypass an uncertain effect.

nextStep uses analytics_tools_get with the original channelCode; existingPhase is retained. No initialization, save or recache is repeated by the history read.

Saved record identity

A missing record and a malformed existing record are different. If the stored JSON is null, false, zero or an empty string, apply/dry-run/status/resume return TASK_STATE_UNVERIFIED; they do not start new work, replace the record, or report it as absent. Preserve it for operator inspection. Do not delete/edit the record or generate a new request ID to bypass the error. Valid stored work and genuinely missing task IDs keep the recovery behavior described above.