https://doc.kotzilla.io/assets/js/bce08f93.6ccd5abd.js

1"use strict";(self.webpackChunkkoin_website=self.webpackChunkkoin_website||[]).push([[9371],{6894:(e,t,n)=>{n.r(t),n.d(t,{assets:()=>d,contentTitle:()=>a,default:()=>h,frontMatter:()=>s,metadata:()=>i,toc:()=>c});const i=JSON.parse('{"id":"settings/pluginConfig","title":"Kotzilla Gradle plugin configuration","description":"Reference for the Kotzilla Gradle plugin kotzilla {} DSL options and the build report, applicable to both Version Catalog and legacy Gradle setups.","source":"@site/docs/settings/pluginConfig.md","sourceDirName":"settings","slug":"/settings/pluginConfig","permalink":"/docs/settings/pluginConfig","draft":false,"unlisted":false,"editUrl":null,"tags":[],"version":"current","frontMatter":{"title":"Kotzilla Gradle plugin configuration","description":"Reference for the Kotzilla Gradle plugin kotzilla {} DSL options and the build report, applicable to both Version Catalog and legacy Gradle setups."},"sidebar":"docs","previous":{"title":"Configure Kotzilla repository","permalink":"/docs/settings/repository"},"next":{"title":"Automatic start (early start)","permalink":"/docs/settings/earlyStart"}}');var l=n(4848),r=n(8453),o=n(5260);const s={title:"Kotzilla Gradle plugin configuration",description:"Reference for the Kotzilla Gradle plugin kotzilla {} DSL options and the build report, applicable to both Version Catalog and legacy Gradle setups."},a=void 0,d={},c=[{value:"Kotzilla DSL Reference",id:"kotzilla-dsl-reference",level:2},{value:"Custom endpoint",id:"custom-endpoint",level:2},{value:"Runtime debug logs from the plugin",id:"runtime-debug-logs-from-the-plugin",level:2},{value:"Default Changes in SDK 2.0.x",id:"default-changes-in-sdk-20x",level:3},{value:"Build Report",id:"build-report",level:2},{value:"Overriding the failure gate from CI/CD",id:"overriding-the-failure-gate-from-cicd",level:3},{value:"Plugin application",id:"plugin-application",level:2},{value:"KSP task ordering",id:"ksp-task-ordering",level:2}];function u(e){const t={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsxs)(o.A,{children:[(0,l.jsx)("title",{children:"Kotzilla Gradle Plugin Configuration \u2013 Kotzilla"}),(0,l.jsx)("meta",{name:"description",content:"Reference for the Kotzilla Gradle plugin kotzilla {} DSL options and the build report, applicable to both Version Catalog and legacy Gradle setups."})]}),"\n",(0,l.jsxs)(t.p,{children:["This page documents the Kotzilla Gradle plugin configuration. It applies to all setups, whether you declare the plugin through a Version Catalog (the default in the setup guides) or through the ",(0,l.jsx)(t.a,{href:"/docs/settings/gradleSetup",children:"legacy Gradle configuration"}),"."]}),"\n",(0,l.jsx)(t.h2,{id:"kotzilla-dsl-reference",children:"Kotzilla DSL Reference"}),"\n",(0,l.jsxs)(t.p,{children:["The ",(0,l.jsx)(t.code,{children:"kotzilla {}"})," block provides configuration options for the Gradle plugin:"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-kotlin",children:'kotzilla {\n    enabled = true                      // Master switch (default: true)\n    versionName = "1.0.0"               // Auto-detected if omitted\n    site = "gateway.kotzilla.io"        // Custom self-hosted gateway URL (optional)\n    projectFile = "kotzilla.json"       // Custom config path (optional)\n    uploadMappingFile = true            // ProGuard mapping upload (default: true)\n    composeInstrumentation = true       // Compose NavHost tracking (default: true)\n    obfuscateGeneratedConfig = true     // Encodes API key to avoid visibility in bundle (default: true)\n    autoInjectXcodeScript = true        // iOS dSYM script (default: true)\n    autoAddDependencies = true          // Auto-add SDK deps (default: true)\n    displayLogs = false                 // Debug logging (default: false) \u2014 also enables runtime logs, see below\n    skipBuildReportFailure = true       // Don\'t fail the build on a FAIL report (default: true)\n    buildReport = true                  // Fetch the build report after assemble (default: true)\n\n    // Consent \u2014 see the Privacy & user consent page\n    consentRequired = false             // Gate all telemetry behind user consent (default: false)\n\n    // Automatic start \u2014 see the Automatic start (early start) page\n    earlyStart = true                   // Auto-boot the SDK at process start (default: true)\n    androidEarlyStart = true            // Per-platform overrides; inherit earlyStart if omitted\n    iosEarlyStart = true\n    jvmEarlyStart = true\n}\n'})}),"\n",(0,l.jsxs)(t.admonition,{title:"New in SDK 2.3.0",type:"tip",children:[(0,l.jsxs)(t.p,{children:[(0,l.jsx)(t.code,{children:"consentRequired"})," and the ",(0,l.jsx)(t.code,{children:"earlyStart"})," family are new in 2.3.0. All are backward-compatible defaults \u2014 upgrading changes no behaviour unless you set them."]}),(0,l.jsxs)(t.ul,{children:["\n",(0,l.jsxs)(t.li,{children:[(0,l.jsx)(t.strong,{children:"Consent gate"})," \u2192 ",(0,l.jsx)(t.a,{href:"/docs/settings/privacyConsent",children:"Privacy & user consent"})]}),"\n",(0,l.jsxs)(t.li,{children:[(0,l.jsx)(t.strong,{children:"Automatic start"})," \u2192 ",(0,l.jsx)(t.a,{href:"/docs/settings/earlyStart",children:"Automatic start (early start)"})]}),"\n"]})]}),"\n",(0,l.jsx)(t.h2,{id:"custom-endpoint",children:"Custom endpoint"}),"\n",(0,l.jsxs)(t.p,{children:["By default the SDK connects to the managed Kotzilla gateway. If you run a ",(0,l.jsx)(t.strong,{children:"self-hosted"})," gateway, point the build at it with ",(0,l.jsx)(t.code,{children:"site"})," (scheme required):"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-kotlin",children:'kotzilla {\n    site = "https://your-gateway.example.com"\n}\n'})}),"\n",(0,l.jsxs)(t.p,{children:["The endpoint is baked into the generated config and read by the runtime on ",(0,l.jsx)(t.strong,{children:"every"})," path \u2014 including early start (auto-boot). Mapping/dSYM uploads and the build report resolve to the same gateway, so runtime and uploads stay consistent."]}),"\n",(0,l.jsx)(t.h2,{id:"runtime-debug-logs-from-the-plugin",children:"Runtime debug logs from the plugin"}),"\n",(0,l.jsxs)(t.p,{children:[(0,l.jsx)(t.code,{children:"displayLogs = true"})," enables verbose plugin logs at build time ",(0,l.jsx)(t.strong,{children:"and"})," \u2014 since SDK 2.3.0 \u2014 runtime SDK debug logs. The value is baked into the generated config and applied at connect, so the early-start path (which has no ",(0,l.jsx)(t.code,{children:"onConfig"})," lambda) can turn runtime logging on."]}),"\n",(0,l.jsx)(t.admonition,{type:"caution",children:(0,l.jsxs)(t.p,{children:[(0,l.jsx)(t.code,{children:"displayLogs = true"})," is a one-way master switch: it forces runtime logs on and cannot be disabled by ",(0,l.jsx)(t.code,{children:"onConfig { useDebugLogs = false }"}),". Runtime debug logs include the bearer token \u2014 never ship a build with ",(0,l.jsx)(t.code,{children:"displayLogs = true"}),"."]})}),"\n",(0,l.jsx)(t.h3,{id:"default-changes-in-sdk-20x",children:"Default Changes in SDK 2.0.x"}),"\n",(0,l.jsxs)(t.table,{children:[(0,l.jsx)(t.thead,{children:(0,l.jsxs)(t.tr,{children:[(0,l.jsx)(t.th,{children:"Option"}),(0,l.jsx)(t.th,{children:"1.4.x Default"}),(0,l.jsx)(t.th,{children:"2.0.x Default"})]})}),(0,l.jsxs)(t.tbody,{children:[(0,l.jsxs)(t.tr,{children:[(0,l.jsx)(t.td,{children:(0,l.jsx)(t.code,{children:"composeInstrumentation"})}),(0,l.jsx)(t.td,{children:"false"}),(0,l.jsx)(t.td,{children:(0,l.jsx)(t.strong,{children:"true"})})]}),(0,l.jsxs)(t.tr,{children:[(0,l.jsx)(t.td,{children:(0,l.jsx)(t.code,{children:"autoInjectXcodeScript"})}),(0,l.jsx)(t.td,{children:"false"}),(0,l.jsx)(t.td,{children:(0,l.jsx)(t.strong,{children:"true"})})]}),(0,l.jsxs)(t.tr,{children:[(0,l.jsx)(t.td,{children:(0,l.jsx)(t.code,{children:"obfuscateGeneratedConfig"})}),(0,l.jsx)(t.td,{children:"N/A"}),(0,l.jsx)(t.td,{children:(0,l.jsx)(t.strong,{children:"true"})})]}),(0,l.jsxs)(t.tr,{children:[(0,l.jsx)(t.td,{children:(0,l.jsx)(t.code,{children:"autoAddDependencies"})}),(0,l.jsx)(t.td,{children:"N/A"}),(0,l.jsx)(t.td,{children:(0,l.jsx)(t.strong,{children:"true"})})]})]})]}),"\n",(0,l.jsx)(t.h2,{id:"build-report",children:"Build Report"}),"\n",(0,l.jsxs)(t.p,{children:["Since SDK 2.2.0, Gradle builds print the Kotzilla report for the selected app version, run by auto-wired ",(0,l.jsx)(t.code,{children:"kotzillaBuildReport{Variant}"})," tasks, so regressions are visible at build time without leaving your build."]}),"\n",(0,l.jsxs)(t.p,{children:["Since SDK 2.2.4, a ",(0,l.jsx)(t.code,{children:"FAIL"})," report status ",(0,l.jsx)(t.strong,{children:"no longer blocks the build by default"})," (",(0,l.jsx)(t.code,{children:"skipBuildReportFailure = true"}),"): the report banner still prints, but the build stays green. This avoids blocking your first build, before any data exists for the app version. To turn the report into a hard build gate, set ",(0,l.jsx)(t.code,{children:"skipBuildReportFailure = false"})," in the ",(0,l.jsx)(t.code,{children:"kotzilla {}"})," block of your app, shared, or ComposeApp module:"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-kotlin",children:"kotzilla {\n    skipBuildReportFailure = false   // fail the build when the report status is FAIL\n}\n"})}),"\n",(0,l.jsxs)(t.p,{children:[(0,l.jsx)(t.code,{children:"PASS"}),", ",(0,l.jsx)(t.code,{children:"404"})," (no data yet), and transient HTTP errors never fail the build."]}),"\n",(0,l.jsx)(t.h3,{id:"overriding-the-failure-gate-from-cicd",children:"Overriding the failure gate from CI/CD"}),"\n",(0,l.jsxs)(t.p,{children:["You can flip the gate per build ",(0,l.jsxs)(t.strong,{children:["without editing ",(0,l.jsx)(t.code,{children:"build.gradle.kts"})]})," using a Gradle property. The property wins over the DSL value when present:"]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-bash",children:"./gradlew assemble -Pkotzilla.skipBuildReportFailure=false   # force the gate ON (fail on FAIL)\n./gradlew assemble -Pkotzilla.skipBuildReportFailure=true    # force the gate OFF (informational only)\n"})}),"\n",(0,l.jsxs)(t.p,{children:["Any value other than ",(0,l.jsx)(t.code,{children:"true"})," / ",(0,l.jsx)(t.code,{children:"false"}

1)," is ignored, and the DSL value applies. This is handy when you want local and PR builds to stay green but a release pipeline to fail on a ",(0,l.jsx)(t.code,{children:"FAIL"})," report."]}),"\n",(0,l.jsx)(t.p,{children:"The build report applies to all project types (Android, Android with Compose, KMP, CMP, and SDK Library for Android)."}),"\n",(0,l.jsx)(t.h2,{id:"plugin-application",children:"Plugin application"}),"\n",(0,l.jsxs)(t.p,{children:["Since SDK 2.2.0, the Kotzilla Gradle plugin is applied at the root with ",(0,l.jsx)(t.code,{children:"apply true"}),". This makes the plugin process every module in your project, including feature modules with Compose Navigation routes, so screens owned by feature modules are reported in production."]}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-kotlin",children:"// root build.gradle.kts (Version Catalog)\nplugins {\n    alias(libs.plugins.kotzilla) apply true\n}\n"})}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-kotlin",children:'// root build.gradle.kts (legacy)\nplugins {\n    id("io.kotzilla.kotzilla-plugin") version "2.3.6" apply true\n}\n'})}),"\n",(0,l.jsx)(t.p,{children:"The module-level plugin application stays as before in your app, shared, or ComposeApp module. Feature modules do not need a Kotzilla API key; only your app or main runtime module does."}),"\n",(0,l.jsx)(t.h2,{id:"ksp-task-ordering",children:"KSP task ordering"}),"\n",(0,l.jsxs)(t.p,{children:["The plugin generates its config (",(0,l.jsx)(t.code,{children:"generateKotzillaConfig"}),") into a Kotlin source set that KSP-based tools also read. When your build uses KSP, for example Hilt, Dagger, Room, or Moshi, Gradle can fail validation because the KSP tasks and ",(0,l.jsx)(t.code,{children:"generateKotzillaConfig"})," touch the same source set without a declared dependency between them."]}),"\n",(0,l.jsx)(t.p,{children:"Add task ordering so the config is generated before any KSP task runs:"}),"\n",(0,l.jsx)(t.pre,{children:(0,l.jsx)(t.code,{className:"language-kotlin",children:'subprojects {\n    tasks.matching { it.name.startsWith("ksp") }.configureEach {\n        dependsOn(tasks.matching { it.name.startsWith("generateKotzillaConfig") })\n    }\n}\n'})}),"\n",(0,l.jsx)(t.p,{children:"This applies to Koin and non-Koin projects alike, since the trigger is KSP, not the DI framework."})]})}function h(e={}){const{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,l.jsx)(t,{...e,children:(0,l.jsx)(u,{...e})}):u(e)}},8453:(e,t,n)=>{n.d(t,{R:()=>o,x:()=>s});var i=n(6540);const l={},r=i.createContext(l);function o(e){const t=i.useContext(r);return i.useMemo((function(){return"function"==typeof e?e(t):{...t,...e}}),[t,e])}function s(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:o(e.components),i.createElement(r.Provider,{value:t},e.children)}}}]);