Best Practices

This page outlines recommended practices for using Intellitoggle in real-world applications. Following these guidelines will help you avoid common pitfalls, improve reliability, and maintain clean flag management over time.

1. Flag Lifecycle Management

  • Create with intent: Always define the purpose of a flag before adding it.

  • Name consistently: Use clear, descriptive keys (checkout_experiment_v2, not flag123).

  • Expire old flags: Remove flags once the experiment or rollout is complete.

  • Track ownership: Assign teams or individuals to maintain each flag.

2. Environment Separation

  • Use different API keys for development, staging, and production.

  • Never reuse production credentials in development or testing.

  • Validate flag behavior in staging before rollout to production.

3. Context Hygiene

  • Send only attributes required for evaluation (minimize sensitive data).

  • Use privateAttributes to protect sensitive fields from logs.

  • Define consistent context schemas across your services.

4. Rollout Strategies

  • Start with percentage rollouts before enabling flags globally.

  • Use targeting by role, plan, or region for safer incremental launches.

  • Monitor metrics (errors, latency, usage) during a rollout.

5. Error Handling

  • Always provide a default value when evaluating a flag.

  • Handle common exceptions such as FlagNotFoundException or AuthenticationException.

  • Configure retry options and sensible timeouts in IntelliToggleOptions.

6. Performance & Reliability

  • Initialize the SDK once, early in your application lifecycle.

  • Use caching and polling to reduce API calls in high-throughput apps.

  • Prefer streaming updates where supported for near real-time flag changes.

7. Collaboration & Governance

  • Document the purpose of each flag in your team’s knowledge base.

  • Regularly review active flags to avoid clutter.

  • Implement naming conventions (e.g., teamName_featureName_experiment).

  • Link flags to issue tracker IDs or change requests for traceability.

8. Observability

  • Add logging hooks to record flag evaluations.

  • Track flag decisions in analytics for feature adoption insights.

  • Correlate flag rollouts with monitoring dashboards (e.g., errors, performance metrics).

9. Flutter & UI Best Practices

  • Avoid evaluating flags directly inside widget build methods; prefer FutureBuilder or Provider.

  • Keep UI fallbacks simple — don’t rely on flags for critical rendering paths.

  • Test flag variations with QA before production rollout.

10. Security & Privacy

  • Never hardcode API keys in source code; use environment variables or secret managers.

  • Rotate credentials regularly.

  • Review the Security & Privacy page for more guidance.