Hooks

Overview

This topic explains how to define and add hooks to LaunchDarkly SDKs. Hooks are collections of developer-defined callbacks. They contain methods that the SDK executes at various points of interest.

In LaunchDarkly SDKs, hooks provide entry points to observe or modify aspects of SDK operation. For example, when you enable OpenTelemetry in a server-side SDK, you add a tracing hook, provided by LaunchDarkly, that surfaces telemetry data. You might also write your own hook, for instance to support logging or reporting errors.

Hooks define an “evaluation” series, which is composed of two stages: beforeEvaluation and afterEvaluation. When you include a hook in your SDK configuration, the SDK executes these two stages before and after the evaluation of a feature flag.

Details about how to add hooks to each SDK are available in the SDK-specific sections below.

Server-side SDKs

This feature is available in the following SDKs:

.NET (server-side)

To use hook functionality with the .NET (server-side) SDK, first import the LaunchDarkly.Sdk.Server.Hooks namespace. Then, define a new hook. This class must derive from the Hook class and override its methods. Finally, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

.NET (server-side), v8.4+
1using LaunchDarkly.Sdk.Server.Hooks;
2
3public class ExampleHook : Hook {
4
5  // Implement at least one of `BeforeEvaluation`, `AfterEvaluation`
6
7  // `BeforeEvaluation` is called during the execution of a variation method
8  // before the flag value has been determined
9
10  // `AfterEvaluation` is called during the execution of a variation method
11  // after the flag value has been determined
12
13}
14
15var exampleHook = new ExampleHook();
16
17var config = Configuration.Builder("sdk-key-123abc")
18  .Hooks(Components.Hooks()
19    .Add(exampleHook)
20  ).Build();
21
22var client = new LdClient(config);

To learn more, read Hooks.

Go

To use hook functionality with the Go SDK, first import the ldhooks package. Then, define a new hook. It must implement the Hook interface. Finally, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

Go SDK, v7.4+
1import (
2  ld "github.com/launchdarkly/go-server-sdk/v7"
3  "github.com/launchdarkly/go-server-sdk/v7/ldhooks"
4)
5
6type exampleHook struct {
7  ldhooks.Unimplemented
8  metadata ldhooks.Metadata
9}
10
11func (e exampleHook) Metadata() ldhooks.Metadata {
12  return e.metadata
13}
14
15// Implement at least one of `BeforeEvaluation`, `AfterEvaluation`
16
17// `BeforeEvaluation` is called during the execution of a variation method
18// before the flag value has been determined
19
20// `AfterEvaluation` is called during the execution of a variation method
21// after the flag value has been determined
22
23func newExampleHook() exampleHook {}
24
25var config ld.Config
26
27client, _ = ld.MakeCustomClient("sdk-key-123abc",
28  ld.Config{
29    Hooks: []ldhooks.Hook{newExampleHook()},
30  }, 5*time.Second)

To learn more, read Hook.

Java

To use hook functionality with the Java SDK, first define a new hook. This class must implement the Hook abstract class. Then, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

Java SDK, v7.4+
1import com.launchdarkly.sdk.server.integrations.Hook;
2
3class ExampleHook extends Hook {
4
5  public ExampleHook(String name) {
6    super(name);
7  }
8
9  // Implement at least one of `beforeEvaluation`, `afterEvaluation`
10
11  // `beforeEvaluation` is called during the execution of a variation method
12  // before the flag value has been determined
13
14  // `afterEvaluation` is called during the execution of a variation method
15  // after the flag value has been determined
16}
17
18ExampleHook exampleHook = new ExampleHook();
19
20LDConfig config = new LDConfig.Builder()
21    .hooks(
22        Components.hooks().setHooks(Collections.singletonList(exampleHook)))
23    .build();
24
25LDClient client = new LDClient("sdk-key-123abc", config);

To learn more, read Hook.

Node.js (server-side)

To use hook functionality with the Node.js (server-side) SDK, first define a new hook. This class must extend the Hook interface. Then, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

Node.js (server-side) SDK, v9.3+
1export class ExampleHook implements integrations.Hook {
2
3  getMetadata() {
4    return { name: 'Example hook'}
5  }
6
7  // Implement at least one of `beforeEvaluation`, `afterEvaluation`
8
9  // `beforeEvaluation` is called during the execution of a variation method
10  // before the flag value has been determined
11
12  // `afterEvaluation` is called during the execution of a variation method
13  // after the flag value has been determined
14}
15
16const options: ld.LDOptions = {
17  hooks: [new ExampleHook()]
18};
19
20const client = ld.init('sdk-key-123abc', options);

You can also add a hook to an existing client using the addHook method:

Node.js (server-side) SDK, v9.3+
1const client = ld.init('sdk-key-123abc', options);
2client.addHook(new ExampleHook());

To learn more, read Hook.

Python

To use hook functionality with the Python SDK, first define a new hook. This class must inherit from ldclient.hook.Hook. Then, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

Python, v9.4+
1import ldclient
2
3from ldclient import Config
4from ldclient.hook import Hook, Metadata
5
6
7class ExampleHook(Hook):
8    @property
9    def metadata(self) -> Metadata:
10        return Metadata(name="example-hook")
11
12    # Implement at least one of `before_evaluation`, `before_evaluation`
13
14    # `before_evaluation` is called during the execution of a variation method
15    # before the flag value has been determined
16
17    # `after_evaluation` is called during the execution of a variation method
18    # after the flag value has been determined
19
20
21example_hook = ExampleHook()
22
23config = Config("sdk-key-123abc", hooks=[example_hook])
24
25ldclient.set_config(config=config)
26client = ldclient.get()

You can also add a hook to an existing client using the add_hook method:

Python, v9.4+
1ldclient.set_config(config=config)
2client = ldclient.get()
3
4client.add_hook(example_hook)

To learn more, read ldclient.hook.

Ruby

To use hook functionality with the Ruby SDK, first define a new hook. This class must include the Hooks mixin. Then, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

Ruby, v8.4+
1require 'ldclient-rb'
2
3class ExampleHook
4  include LaunchDarkly::Interfaces::Hooks::Hook
5
6  def metadata
7    LaunchDarkly::Interfaces::Hooks::Metadata.new('example-hook')
8  end
9
10  # Implement at least one of `before_evaluation`, `after_evaluation`
11
12  # `before_evaluation` is called during the execution of a variation method
13  # before the flag value has been determined
14
15  # `after_evaluation` is called during the execution of a variation method
16  # after the flag value has been determined
17end
18
19example_hook = ExampleHook.new
20
21config = LaunchDarkly::Config.new(hooks: [example_hook])
22
23client = LaunchDarkly::LDClient.new("sdk-key-123abc", config)

You can also add a hook to an existing client using the add_hook method:

Ruby, v8.4+
1client = LaunchDarkly::LDClient.new("sdk-key-123abc", config)
2
3client.add_hook(example_hook)

To learn more, read Hooks.

Client-side SDKs

This feature is available in the following SDKs:

iOS

To use hook functionality with the iOS SDK, first define a new hook. This class must use the Hook protocol. Then, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

iOS, v9.7.2+ (Swift)
1import LaunchDarkly
2
3class ExampleHook: Hook {
4    func metadata() -> Metadata {
5        return Metadata(name: "example-hook")
6    }
7
8    /// Implement at least one of `beforeEvaluation`, `afterEvaluation`
9
10    /// beforeEvaluation is called during the execution of a variation method
11    /// before the flag value has been determined
12
13    /// afterEvaluation is called during the execution of a variation method
14    /// after the flag value has been determined
15}
16
17let exampleHook = ExampleHook()
18
19var config = LDConfig(
20  mobileKey: "mobile-key-123abc",
21  autoEnvAttributes: .enabled
22)
23config.hooks = [exampleHook]
24
25let context = try! LDContextBuilder(key: "context-key-123abc").build().get()
26
27LDClient.start(config: config, context: context, startWaitSeconds: 5) { timedOut in
28    if timedOut {
29        /// Client may not have the most recent flags for the configured context
30    } else {
31        /// Client has received flags for the configured context
32    }
33}

To learn more, read Hook.

React Native

To use hook functionality with the React Native SDK, first define a new hook. This class must extend the Hook interface. Then, reference the hook in the configuration options when you initialize the SDK client.

Here’s how:

React Native SDK, v10+
1export class ExampleHook implements Hook {
2
3  getMetadata() {
4    return { name: 'Example hook'}
5  }
6
7  // Implement at least one of `beforeEvaluation`, `afterEvaluation`
8
9  // `beforeEvaluation` is called during the execution of a variation method
10  // before the flag value has been determined
11
12  // `afterEvaluation` is called during the execution of a variation method
13  // after the flag value has been determined
14}
15
16const options: ld.LDOptions = {
17  hooks: [new ExampleHook()]
18};
19
20const client = new ReactNativeLDClient('mobile-key-123abc', AutoEnvAttributes.Enabled, options);

You can also add a hook to an existing client using the addHook method:

React Native SDK, v10+
1const client = new ReactNativeLDClient('mobile-key-123abc', AutoEnvAttributes.Enabled, options);
2client.addHook(new ExampleHook());

To learn more, read Hook.

Built with