Segment

https://www.twilio.com/docs/segment
Admin
Segment is a customer data platform that collects, cleans, and activates customer data from your web...
Tokens:129,815
Snippets:990
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### List workspaces with access token

Source: https://www.twilio.com/docs/segment/api/config-api

Sets an access token in the Authorization header and sends a GET request to list workspaces. The example response shows the returned workspace object with name, display_name, id, create_time, and next_page_token.

```shell
$ ACCESS_TOKEN=qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g

$ curl \
  -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://platform.segmentapis.com/v1beta/workspaces
```

```json
{
  "workspaces": [
    {
      "name": "workspaces/myworkspace",
      "display_name": "My Space",
      "id": "e5bdb0902b",
      "create_time": "2018-08-08T13:24:02.651Z"
    }
  ],
  "next_page_token": ""
}
```

--------------------------------

### Example response from workspaces endpoint

Source: https://www.twilio.com/docs/segment/api/config-api/authentication

Shows the JSON response returned by the GET request to the workspaces endpoint, containing a list of workspaces with their name, display_name, id, and create_time.

```json
{
  "workspaces": [
    {
      "name": "myworkspace",
      "display_name": "My Space",
      "id": "e5bdb0902b",
      "create_time": "2018-08-08T13:24:02.651Z"
    }
  ]
}
```

--------------------------------

### Install curl

Source: https://www.twilio.com/docs/segment/api/config-api

Installs curl, which is required to call the Config API from the command line.

```shell
$ brew install curl
```

--------------------------------

### Install and initialize Segment PHP library

Source: https://www.twilio.com/docs/segment/getting-started/02-simple-install

Install the Segment PHP library by cloning the repository, then load it in your script and initialize it once with your write key. Replace YOUR_WRITE_KEY with your actual key from Segment project settings; otherwise data goes to /dev/null. The default consumer is the libcurl consumer, but you can switch to others like fork-curl for high-volume projects.

```bash
git clone https://github.com/segmentio/analytics-php /my/application/folders/
```

```php
require_once("/path/to/analytics-php/lib/Segment.php");
use Segment\Segment;
```

```php
# Set up our Segment tracking and
# alias to Analytics for convenience
class_alias('Segment', 'Analytics');
Segment::init("YOUR_WRITE_KEY");
```

--------------------------------

### trackLink example

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript

Example binding a Track call to a link element with properties.

```javascript
var link = document.getElementById('free-trial-link');

analytics.trackLink(link, 'Clicked Free-Trial Link', {
  plan: 'Enterprise'
});
```

--------------------------------

### Install com.segment.analytics.csharp via OpenUPM for Unity

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/server/csharp

Adds the Analytics-CSharp package to a Unity project using the OpenUPM CLI.

```bash
openupm add com.segment.analytics.csharp
```

--------------------------------

### SQL query example: select users where first_name equals Alice

Source: https://www.twilio.com/docs/segment/glossary

Illustrates SQL syntax for retrieving users with a specific first name. The example uses 'equals' instead of the standard '=' operator, which is non-standard SQL.

```sql
select * from users where first_name equals "Alice"
```

--------------------------------

### Track call example

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript

Example Track call tracking an 'Article Completed' event with properties.

```javascript
analytics.track('Article Completed', {
  title: 'How to Create a Tracking Plan',
  course: 'Intro to Analytics',
});
```

--------------------------------

### DestinationPlugin example for Amplitude

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/server/csharp

Implements a device-mode destination plugin for Amplitude. Initializes the Amplitude SDK and logs track events. The Key property is used to retrieve settings internally.

```csharp
class AmplitudePlugin : DestinationPlugin
{
    public override string Key =>
        "Amplitude"; // This is the name of the destination plugin, it is used to retrieve settings internally
    private Amplitude amplitudeSDK: // This is an instance of the partner SDK
    public AmplitudePlugin()
    {
        amplitudeSDK = Amplitude.instance;
        amplitudeSDK.initialize(applicationContext, "API_KEY");
    }
    /*
    * Implementing this function allows this plugin to hook into any track events
    * coming into the analytics timeline
    */
    public override TrackEvent Track(TrackEvent trackEvent)
    {
        amplitudeSDK.logEvent(trackEvent.Event);
        return trackEvent;
    }
}
```

--------------------------------

### Track a sign-up event with analytics.track

Source: https://www.twilio.com/docs/segment/getting-started/02-simple-install

Use this snippet to track a user action, such as signing up. The event name and properties can be customized. This example tracks a 'Signed Up' event with a 'plan' property.

```JavaScript
analytics.track('Signed Up', {
  plan: 'Enterprise'
});
```

--------------------------------

### Track a user sign-up event with Segment iOS SDK

Source: https://www.twilio.com/docs/segment/getting-started/02-simple-install

Track a user sign-up event with a custom property. The example uses the 'Signed Up' event and a 'plan' property.

```objc
[[SEGAnalytics sharedAnalytics] track:@"Signed Up"
                           properties:@{ @"plan": @"Enterprise" }];
```

--------------------------------

### Install Segment.Analytics.CSharp via NuGet

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/server/csharp

Adds the Segment.Analytics.CSharp package to a .NET project using the dotnet CLI. Replace <LATEST_VERSION> with the current version from NuGet.

```bash
dotnet add package Segment.Analytics.CSharp --version <LATEST_VERSION>
```

--------------------------------

### Initialize Analytics client with Configuration

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/server/csharp

Creates a Configuration with your write key, flushAt, and flushInterval, then initializes the Analytics client. To make Analytics stateless/in-memory, add InMemoryStorageProvider to the configuration.

```c#
// NOTE: to make Analytics stateless/in-memory,
// add `InMemoryStorageProvider` to the configuration
var configuration = new Configuration("<YOUR WRITE KEY>",
    flushAt: 20,
    flushInterval: 30);
var analytics = new Analytics(configuration);
```

--------------------------------

### Install and initialize Analytics-iOS with CocoaPods

Source: https://www.twilio.com/docs/segment/getting-started/02-simple-install

Add pod 'Analytics', '~> 3.0' to your Podfile. In application:didFinishLaunchingWithOptions:, create a SEGAnalyticsConfiguration with your write key, optionally enable trackApplicationLifecycleEvents and recordScreenViews, then call setupWithConfiguration:. Import <Analytics/SEGAnalytics.h> in files that use the SDK.

```ruby
pod 'Analytics', '~> 3.0'
```

```objective-c
SEGAnalyticsConfiguration *configuration = [SEGAnalyticsConfiguration configurationWithWriteKey:@"YOUR_WRITE_KEY"];
configuration.trackApplicationLifecycleEvents = YES; // Enable this to record certain application events automatically!
configuration.recordScreenViews = YES; // Enable this to record screen views automatically!
[SEGAnalytics setupWithConfiguration:configuration];
```

```objective-c
#import <Analytics/SEGAnalytics.h>
```

--------------------------------

### Full Alias workflow example

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/server/java

Shows a complete sequence: tracking an anonymous user, aliasing them to an identified user, identifying them, and tracking an identified action. This demonstrates the typical signup flow.

```java
// the anonymous user does actions ...
track("anonymous_user", "Anonymous Event");
// the anonymous user signs up and is aliased
alias("anonymous_user", "identified@example.com");
// the signed up user is identified
identify("identified@example.com", new Traits("plan", "Free"));
// the identified user does actions ...
track("identified@example.com", "Identified Action");
```

--------------------------------

### FQL Subexpression Examples

Source: https://www.twilio.com/docs/segment/api/config-api/fql

Examples of FQL subexpressions using parentheses to group conditions for complex and/or logic. Each expression evaluates to true or false.

```fql
type = 'track' and ( event = 'Click' or match( 'Button *', event ) )
```

```fql
( type = 'track' or type = 'identify' ) and ( properties.enabled or match( traits.email, '*@company.com' ) )
```

```fql
!( type in ['track', 'identify'] )
```

--------------------------------

### Initialize Analytics-Swift client in didFinishLaunchingWithOptions

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/mobile/apple

Initialize the Analytics-Swift client in the iOS app lifecycle method. Requires a unique writeKey to avoid malformed JSON and 400 errors. Sets lifecycle tracking and a 10-second flush interval.

```swift
    var analytics: Analytics? = nil

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
            // Override point for customization after application launch.
            let configuration = Configuration(writeKey: "WRITE_KEY")
                .trackApplicationLifecycleEvents(true)
                .flushInterval(10)

            analytics = Analytics(configuration: configuration)
    }
```

--------------------------------

### Common fields example in raw JSON

Source: https://www.twilio.com/docs/segment/connections/spec/common

Example of the common fields in a Segment API call, showing user identity, context, integrations, and event metadata. Use this as a reference for the structure of every API call.

```json
{
  "anonymousId": "507f191e810c19729de860ea",
  "context": {
    "active": true,
    "app": {
      "name": "InitechGlobal",
      "version": "545",
      "build": "3.0.1.545",
      "namespace": "com.production.segment"
    },
    "campaign": {
      "name": "TPS Innovation Newsletter",
      "source": "Newsletter",
      "medium": "email",
      "term": "tps reports",
      "content": "image link"
    },
    "device": {
      "id": "B5372DB0-C21E-11E4-8DFC-AA07A5B093DB",
      "advertisingId": "7A3CBEA0-BDF5-11E4-8DFC-AA07A5B093DB",
      "adTrackingEnabled": true,
      "manufacturer": "Apple",
      "model": "iPhone7,2",
      "name": "maguro",
      "type": "ios",
      "token": "ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449"
    },
    "ip": "8.8.8.8",
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    },
    "locale": "en-US",
    "network": {
      "bluetooth": false,
      "carrier": "T-Mobile US",
      "cellular": true,
      "wifi": false
    },
    "os": {
      "name": "iPhone OS",
      "version": "8.1.3"
    },
    "page": {
      "path": "/academy/",
      "referrer": "",
      "search": "",
      "title": "Analytics Academy",
      "url": "https://segment.com/academy/"
    },
    "referrer": {
      "id": "ABCD582DEFFFF01919",
      "type": "dataxu"
    },
    "screen": {
      "width": 320,
      "height": 568,
      "density": 2
    },
    "groupId": "12345",
    "timezone": "Europe/Amsterdam",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36",
    "userAgentData": {
      "brands": [
        {
          "brand": "Google Chrome",
          "version": "113"
        },
        {
          "brand": "Chromium",
          "version": "113"
        },
        {
          "brand": "Not-A.Brand",
          "version": "24"
        }
      ],
      "mobile": false,
      "platform": "macOS"
    }
  },
  "integrations": {
    "All": true,
    "Mixpanel": false,
    "Salesforce": false
  },
  "event": "Report Submitted",
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "receivedAt": "2015-12-10T04:08:31.909Z",
  "sentAt": "2015-12-10T04:08:31.581Z",
  "timestamp": "2015-12-10T04:08:31.905Z",
  "type": "track",
  "userId": "97980cfea0067",
  "version": 2
}
```

--------------------------------

### Initialize Analytics client in Kotlin

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/mobile/kotlin-android

Create an analytics client with your Segment write key and application context. Configure options like `trackApplicationLifecycleEvents`, `flushAt`, and `flushInterval`. The application context is required as the second parameter.

```java
// Add required imports
import com.segment.analytics.kotlin.android.Analytics
import com.segment.analytics.kotlin.core.*

// Create an analytics client with the given application context and Segment write key.
// NOTE: in android, application context is required to pass as the second parameter.
Analytics("YOUR_WRITE_KEY", applicationContext) {
  // Automatically track Lifecycle events
  trackApplicationLifecycleEvents = true
  flushAt = 3
  flushInterval = 10
}
```

--------------------------------

### addSourceMiddleware enrichment and validation examples

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript

Two examples of using addSourceMiddleware: one for enrichment (lowercasing the event name for track events) and one for validation (dropping invalid events by returning null). Both run before other plugins and can modify or drop events.

```js
analytics.addSourceMiddleware(({ payload, next }) => {
   const { event } = payload.obj.context
   if (event.type === 'track') {
      event.event.toLowerCase()
   }
   next(payload)
});
```

```js
analytics.addSourceMiddleware(({ payload, next }) => {
  const { event } = payload.obj.context
  if (!isValid(event)) {
    return null // event is dropped
  }
  next(payload)
});
```

--------------------------------

### Identify call example

Source: https://www.twilio.com/docs/segment/getting-started/04-full-install

Example Identify call that identifies a user, Michael Phillips, a customer who lives in New York, New York. The call passes a user_id and traits including email, name, city, state, and internal. The userId is the most important trait to pass, and should be a unique hash value.

```js
analytics.identify (user_id: "12345abcde",
  traits: {
    email: 'michael.phillips@segment.com',
    name: 'Michael Phillips',
    city: 'New York',
    state: 'NY',
    internal: True })
```

--------------------------------

### Track user actions with Segment::track

Source: https://www.twilio.com/docs/segment/getting-started/02-simple-install

Track user actions with the Track method. The first example tracks a 'Signed Up' event with a plan property; the second tracks an 'Article Bookmarked' event with article properties. Properties can be anything you want to record. Recommended events include Signed Up, Item Purchased, or Article Bookmarked.

```php
Segment::track(array(
  "userId" => "f4ca124298",
  "event" => "Signed Up",
  "properties" => array(
    "plan" => "Enterprise"
  )
));
```

```php
Segment::track(array(
  "userId" => "f4ca124298",
  "event" => "Article Bookmarked",
  "properties" => array(
    "title" => "Snow Fall",
    "subtitle" => "The Avalanche at Tunnel Creek",
    "author" => "John Branch"
  )
));
```

--------------------------------

### Track 'Article Bookmarked' event in JavaScript and Ruby

Source: https://www.twilio.com/docs/segment/getting-started/04-full-install

Track an 'Article Bookmarked' event with properties in JavaScript and Ruby. The JavaScript example uses a string event name and an object literal; the Ruby example uses a user_id, event, and properties hash. Both follow Segment's Track method syntax.

```js
analytics.track('Article Bookmarked', {
  "title": 'How to Create a Tracking Plan',
  "course": 'Intro to Data Strategy',
  "author": 'Dr. Anna Lytics',
});
```

```ruby
analytics.track( user_id: '12345abcde',
  event: 'Article Bookmarked',
  properties: {
     title: 'How to Create a Tracking Plan',
     course: 'Intro to Data Strategy',
     author: 'Dr. Anna Lytics'})
```

--------------------------------

### Initialize Segment Analytics in Objective-C

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/mobile/apple

Initializes the Segment Analytics client in an Objective-C app's application:didFinishLaunchingWithOptions: method. Sets the write key, enables automatic lifecycle tracking, and sends example track events. Requires importing the Segment module and replacing WRITE_KEY with your actual write key.

```objc
  @import Segment;
  ...

  - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      // Override point for customization after application launch.
      SEGConfiguration *config = [[SEGConfiguration alloc] initWithWriteKey:@"WRITE_KEY"];
      config.trackApplicationLifecycleEvents = YES;

      _analytics = [[SEGAnalytics alloc] initWithConfiguration: config];

      [self.analytics track:@"Example Event"];
      [self.analytics track:@"Example Properties" properties:@{@"email": @"sloth@segment.com"}];

      return YES;
  }
```

--------------------------------

### between

Source: https://www.twilio.com/docs/segment/api/public-api/query-language

Provides time windowing between a start and end value, with optional prefix for relative evaluation.

```APIDOC
## between

### Description
Provides time windowing between a start and end value. You can add a prefix to direct the evaluation to be relative to the timestamp of a different event.

### Syntax
`between({s: Integer} {su: TimeUnit}, {e: Integer} {eu: TimeUnit})`

### Parameters
- **s** (Integer) - Required - Start value.
- **su** (TimeUnit) - Required - Time unit for start: hour(s) or day(s).
- **e** (Integer) - Required - End value.
- **eu** (TimeUnit) - Required - Time unit for end: hour(s) or day(s).

### Return Type
`WindowedFilter`

### Example
`between(7 days, 10 days)`
```

--------------------------------

### Ready method with callback

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript

Registers a callback that runs after Analytics.js finishes initializing and all enabled device-mode destinations load. Use it to access end-tool library methods not covered by Analytics.js, like adding a setting to Mixpanel. The callback is not invoked if any destination throws an error during initialization.

```js
analytics.ready(() => {
  window.mixpanel.set_config({ verbose: true });
});
```

```js
analytics.ready(callback);
```

--------------------------------

### Identify call with traits only

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript

Example of an identify call that only passes traits, useful when the user is not yet identified.

```javascript
analytics.identify({
  nickname: 'Amazing Grace',
  favoriteCompiler: 'A-0',
  industry: 'Computer Science'
});
```

--------------------------------

### Identify call with callback only

Source: https://www.twilio.com/docs/segment/connections/sources/catalog/libraries/website/javascript

Example of an identify call that omits traits and options, passing a callback as the second argument.

```javascript
analytics.identify('12091906-01011992', function(){
  // Do something after the identify request has been sent
  // Note: site-critical functionality should not depend on your analytics provider
});
```
Tokens:
Raw