Create a goal

Create page, event, outbound-link, or scroll-depth conversion goals with the Clics TypeScript SDK.

Defines a new conversion goal for one project. Goals are optional, but they are required for goal conversion statistics and the Goal view in Dashboard.

Every goal has a goalType, a human-readable displayName, and a type-specific rule. The SDK validates the shape before it sends the request.

Parameters

Field	Required	Description
`projectId`	Yes	Parent project
`body.goalType`	Yes	`page`, `event`, `outbound`, or `scroll_depth`
`body.displayName`	Yes	Label shown in Dashboard
`body.envId`	No	`production` (default) or `development`
`body.rule`	Yes	Rule matching the selected `goalType` (below)

Rule for each goal type

`goalType`	Required `body.rule`	Counts a conversion when…
`page`	`{ pagePath: "/pricing" }`	the visitor views the path
`event`	`{ eventName: "purchase" }`	the tracker sends that custom event
`outbound`	`{ outboundUrl: "https://partner.example/join" }`	the visitor clicks that exact external URL
`scroll_depth`	`{ pagePath: "/guide", scrollDepthThreshold: 75 }`	the visitor reaches that percentage on the page

scrollDepthThreshold is a whole number from 1 to 100. Page paths should start with /; a page goal may use one trailing wildcard such as /blog/*.

Signature

clics.goals.createGoal(request, options?)

Example

Page goal:

import { Clics } from "@clicsdev/sdk";

const clics = new Clics({
  apiKey: process.env.CLICS_API_KEY!,
});

const result = await clics.goals.createGoal({
  projectId: "proj_xxx",
  body: {
    goalType: "page",
    displayName: "Pricing visit",
    rule: { pagePath: "/pricing" },
  },
});

Event goal:

const purchase = await clics.goals.createGoal({
  projectId: "proj_xxx",
  body: {
    goalType: "event",
    displayName: "Purchase",
    rule: { eventName: "purchase" },
  },
});

Outbound-link and scroll-depth goals use the same method:

await clics.goals.createGoal({
  projectId: "proj_xxx",
  body: {
    goalType: "outbound",
    displayName: "Partner signup",
    rule: { outboundUrl: "https://partner.example/join" },
  },
});

await clics.goals.createGoal({
  projectId: "proj_xxx",
  body: {
    goalType: "scroll_depth",
    displayName: "Read 75% of guide",
    rule: { pagePath: "/guide", scrollDepthThreshold: 75 },
  },
});

What it returns

The created Goal. Save id to fetch statistics, update it, or delete it later.

Field	Type	Description
`id`	`string`	Stable goal ID, for example `goal_xxx`
`projectId`	`string`	Parent project ID
`envId`	`"production" \| "development"`	Environment in which the goal evaluates traffic
`displayName`	`string`	Label shown in Dashboard
`goalType`	`"page" \| "event" \| "outbound" \| "scroll_depth"`	Determines the shape of `rule`
`rule`	Type-specific object	The configured matching condition, shown below

`goalType`	Returned `rule`
`page`	`{ pagePath: string }`
`event`	`{ eventName: string }`
`outbound`	`{ outboundUrl: string }`
`scroll_depth`	`{ pagePath: string; scrollDepthThreshold: number }`

Notes

Create event goals only after the tracker sends the matching event; see Custom events.
Use envId: "development" only for localhost/development traffic. The project must allow localhost tracking.
SDK property names are camelCase. The SDK translates them to the REST API automatically.

API reference

See Create a goal for request and response schemas, status codes, and error types.