You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This guide contains common integration steps that apply to all Confidence OpenFeature providers in this repository.
4
+
5
+
For language-specific installation and quick start instructions, see your provider's README:
6
+
-[Go Provider](go/README.md)
7
+
-[Java Provider](java/README.md)
8
+
-[JavaScript Provider](js/README.md)
9
+
-[Ruby Provider](ruby/README.md)
10
+
11
+
---
12
+
13
+
## Table of Contents
14
+
15
+
1.[Getting Your Credentials](#getting-your-credentials)
16
+
2.[Error Handling](#error-handling)
17
+
3.[Sticky Assignments](#sticky-assignments)
18
+
19
+
---
20
+
21
+
## Getting Your Credentials
22
+
23
+
Before integrating any Confidence provider, you'll need a **client secret** from your Confidence account:
24
+
25
+
1. Log into the Confidence dashboard
26
+
2. In the **Clients** section, create a new client secret for the client you intend to use (or start by creating a new client)
27
+
3. Make sure to select **Backend** as integration type. Never expose your Backend client secret outside your organization
28
+
29
+
---
30
+
31
+
## Error Handling
32
+
33
+
All Confidence providers use a **default value fallback** pattern to ensure your application continues to function even when flag evaluation fails.
34
+
35
+
### How Default Values Work
36
+
37
+
When you request a flag value, you always provide a default:
38
+
39
+
```
40
+
// Pseudocode
41
+
value = client.getFlagValue("my-flag", DEFAULT_VALUE, context)
42
+
```
43
+
44
+
If anything goes wrong, the provider returns `DEFAULT_VALUE` instead of throwing an error.
45
+
46
+
### Common Failure Scenarios
47
+
48
+
| Scenario | What Happens | Common Causes |
49
+
|----------|--------------|---------------|
50
+
|**Flag doesn't exist**| Returns default | Flag not created, wrong name, not enabled for the client |
51
+
|**Type mismatch**| Returns default | Requesting boolean for string or object property. Or requesting boolean for the _flag_. Flags are objects in Confidence |
|**Provider not ready**| Returns default | Called before initialization complete |
56
+
57
+
### Error Details
58
+
59
+
For debugging, use the `details` methods to get error information:
60
+
61
+
**Error codes:**
62
+
-`FLAG_NOT_FOUND`: The flag doesn't exist in Confidence
63
+
-`TYPE_MISMATCH`: Wrong value type requested (e.g., boolean for string)
64
+
-`PROVIDER_NOT_READY`: Provider still initializing
65
+
-`PARSE_ERROR`: Response couldn't be parsed
66
+
-`GENERAL_ERROR`: Other errors (network, timeout, etc.)
67
+
68
+
**Reasons** (standard OpenFeature reasons):
69
+
-`TARGETING_MATCH`: Flag evaluated successfully and matched targeting rules
70
+
-`DEFAULT`: Default value returned (no segment/variant matched)
71
+
-`DISABLED`: Flag is disabled or archived
72
+
-`STALE`: Stale cached value
73
+
-`ERROR`: Evaluation failed (see error code)
74
+
-`UNKNOWN`: Reason could not be determined
75
+
76
+
### Production Best Practices
77
+
78
+
1.**Choose safe defaults**
79
+
Example:
80
+
```
81
+
✅ GOOD: Default to "off" for risky features
82
+
❌ BAD: Default to "on" for untested code
83
+
```
84
+
85
+
2.**Log errors for debugging**
86
+
- Track evaluation failures in your monitoring system. You can use OpenFeature [hooks](https://openfeature.dev/docs/reference/concepts/hooks/) for this.
87
+
- Include flag key, error code, and context in logs
88
+
- Set up alerts for elevated error rates
89
+
90
+
3.**Monitor error rates**
91
+
- Track `errorCode != null` metrics
92
+
- Alert if error rate exceeds threshold (e.g., >5%)
93
+
- Investigate spikes (may indicate misconfigured flag setup or SDK integration)
Confidence provides **sticky** flag assignments to ensure users receive consistent variant assignments across evaluations. It can be used for two things:
115
+
- Pause intake of new entities to an experiment
116
+
- Ensure that entities are assigned the same variant throughout an experiment even if some of their targeting attributes change during the experiment.
117
+
118
+
### What are Sticky Assignments?
119
+
120
+
When a flag is evaluated for a user, Confidence creates a **materialization** — a snapshot of which variant that user was assigned. On subsequent evaluations, the same variant is returned even if:
121
+
122
+
- The user's context attributes change (e.g., different country, device type)
123
+
- The flag's targeting rules are modified
124
+
- New assignments are paused (controlled rollouts)
125
+
126
+
### How It Works
127
+
128
+
By default, **sticky assignments are managed by Confidence servers**:
129
+
130
+
1. First, the local WASM resolver attempts to resolve the flag
131
+
2. If sticky assignment data is needed, the provider makes a network call to Confidence's cloud resolvers
132
+
3. Materializations are stored on Confidence servers with a **90-day TTL** (automatically renewed on access)
133
+
4. No local storage or database setup required
134
+
135
+
### Benefits
136
+
137
+
-**Zero configuration**: Works out of the box with no additional setup
138
+
-**Managed storage**: Confidence handles all storage and consistency
139
+
-**Global availability**: Materializations are available across all your services that are using this flag
140
+
141
+
### Latency Considerations
142
+
143
+
When a sticky assignment is needed, the provider makes a network call to Confidence's cloud resolvers. This introduces additional latency (the network latency between your location and Confidence servers) compared to local WASM evaluation.
144
+
145
+
### Custom Materialization Storage
146
+
147
+
Some providers support custom storage backends to eliminate network calls for sticky assignments. Check your provider's README for availability and implementation details:
For technical details on how sticky assignments work at the protocol level, including flowcharts, behavior matrices, and configuration patterns, see the [Sticky Assignments Technical Guide](../STICKY_ASSIGNMENTS.md).
@@ -88,36 +152,25 @@ The `ProviderConfig` struct contains all configuration options for the provider:
88
152
#### Optional Fields
89
153
90
154
-`Logger` (*slog.Logger): Custom logger for provider operations. If not provided, a default text logger is created. See [Logging](#logging) for details.
91
-
-`ConnFactory` (func): Custom gRPC connection factory for advanced use cases (e.g., custom interceptors, TLS configuration)
155
+
-`TransportHooks` (TransportHooks): Custom transport hooks for advanced use cases (e.g., custom gRPC interceptors, HTTP transport wrapping, TLS configuration)
92
156
93
157
#### Advanced: Testing with Custom State Provider
94
158
95
-
For testing purposes only, you can provide a custom `StateProvider` to supply resolver state from local sources (e.g., a file cache):
159
+
For testing purposes only, you can provide a custom `StateProvider`and `FlagLogger`to supply resolver state and control logging behavior:
96
160
97
161
```go
98
162
// WARNING: This is for testing only. Do not use in production.
**Important**: This configuration disables automatic state fetching and exposure logging. For production deployments, always use `NewProvider()` with `ProviderConfig`.
110
-
111
-
## Credentials
112
-
113
-
Get your client secret from your [Confidence dashboard](https://confidence.spotify.com/):
114
-
115
-
-`ClientSecret`: The client secret used for authentication and flag evaluation
116
-
117
-
118
-
## WebAssembly Module
119
-
120
-
The WASM module (`confidence_resolver.wasm`) is embedded in the Go binary using Go 1.16+ embed directives. No external WASM file is required at runtime.
173
+
**Important**: This configuration requires you to provide both a `StateProvider` and `FlagLogger`. For production deployments, always use `NewProvider()` with `ProviderConfig`.
The provider logs at different levels: `Debug` (flag resolution details), `Info` (state updates), `Warn` (non-critical issues), and `Error` (failures).
164
217
165
-
## Troubleshooting
166
-
167
-
### Provider Creation Fails
218
+
## Shutdown
168
219
169
-
If provider creation fails, verify:
170
-
-`ClientSecret` is correct
171
-
- Your application has network access to the Confidence CDN
172
-
- Credentials have the necessary permissions in your Confidence dashboard
220
+
**Important**: Always shut down the provider when your application exits to ensure proper cleanup and log flushing.
173
221
174
-
### No Flag Evaluations Work
222
+
```go
223
+
// Shutdown the provider on application exit
224
+
openfeature.Shutdown()
225
+
```
175
226
176
-
Common issues:
177
-
- Ensure you've called `openfeature.SetProviderAndWait(provider)` before creating clients
178
-
- Check that your flags are published and active in Confidence
227
+
### What Happens During Shutdown?
179
228
180
-
### Performance Issues
229
+
1.**Flushes pending logs** to Confidence (exposure events, resolve analytics)
230
+
2.**Closes gRPC connections** and releases network resources
0 commit comments