Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update node README #1205

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update node README #1205

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e1a910f
update node README
silesky Jan 2, 2025
a963b99
wip
silesky Jan 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 1 addition & 114 deletions packages/node/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,123 +54,10 @@ app.post('/cart', (req, res) => {
res.sendStatus(201)
});
```
See our [official documentation](https://segment.com/docs/connections/sources/catalog/libraries/server/node) for more examples and information.


## Settings & Configuration
See the documentation: https://segment.com/docs/connections/sources/catalog/libraries/server/node/#configuration

You can also see the complete list of settings in the [AnalyticsSettings interface](src/app/settings.ts).


## Plugin Architecture
- See segment's [documentation for plugin architecture](https://segment.com/docs/connections/sources/catalog/libraries/website/javascript/#plugin-architecture).



## Usage in non-node runtimes
### Usage in AWS Lambda
- [AWS lambda execution environment](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtime-environment.html) is challenging for typically non-response-blocking async activites like tracking or logging, since the runtime terminates / freezes after a response is emitted.

Here is an example of using analytics.js within a handler:
```ts
const { Analytics } = require('@segment/analytics-node');

// since analytics has the potential to be stateful if there are any plugins added,
// to be on the safe side, we should instantiate a new instance of analytics on every request (the cost of instantiation is low).
const analytics = () => new Analytics({
flushAt: 1,
writeKey: '<MY_WRITE_KEY>',
})
.on('error', console.error);

module.exports.handler = async (event) => {
...
// we need to await before returning, otherwise the lambda will exit before sending the request.
await new Promise((resolve) =>
analytics().track({ ... }, resolve)
)

...
return {
statusCode: 200,
};
....
};
```

### Usage in Vercel Edge Functions
```ts
import { Analytics } from '@segment/analytics-node';
import { NextRequest, NextResponse } from 'next/server';

export const analytics = new Analytics({
writeKey: '<MY_WRITE_KEY>',
flushAt: 1,
})
.on('error', console.error)

export const config = {
runtime: 'edge',
};

export default async (req: NextRequest) => {
await new Promise((resolve) =>
analytics.track({ ... }, resolve)
);
return NextResponse.json({ ... })
};
```

### Usage in Cloudflare Workers
```ts
import { Analytics, Context } from '@segment/analytics-node';

export default {
async fetch(
request: Request,
env: Env,
ctx: ExecutionContext
): Promise<Response> {
const analytics = new Analytics({
flushAt: 1,
writeKey: '<MY_WRITE_KEY>',
}).on('error', console.error);

await new Promise((resolve, reject) =>
analytics.track({ ... }, resolve)
);

...
return new Response(...)
},
};

```

### OAuth 2
In order to guarantee authorized communication between your server environment and Segment's Tracking API, you can [enable OAuth 2 in your Segment workspace](https://segment.com/docs/partners/enable-with-segment/). To support the non-interactive server environment, the OAuth workflow used is a signed client assertion JWT. You will need a public and private key pair where the public key is uploaded to the segment dashboard and the private key is kept in your server environment to be used by this SDK. Your server will verify its identity by signing a token request and will receive a token that is used to to authorize all communication with the Segment Tracking API.

You will also need to provide the OAuth Application ID and the public key's ID, both of which are provided in the Segment dashboard. You should ensure that you are implementing handling for Analytics SDK errors. Good logging will help distinguish any configuration issues.

```ts
import { Analytics, OAuthSettings } from '@segment/analytics-node';
import { readFileSync } from 'fs'

const privateKey = readFileSync('private.pem', 'utf8')

const settings: OAuthSettings = {
clientId: '<CLIENT_ID_FROM_DASHBOARD>',
clientKey: privateKey,
keyId: '<PUB_KEY_ID_FROM_DASHBOARD>',
}

const analytics = new Analytics({
writeKey: '<MY_WRITE_KEY>',
oauthSettings: settings,
})

analytics.on('error', (err) => { console.error(err) })

analytics.track({ userId: 'foo', event: 'bar' })

```
Loading