Simple integration for https://nextjs.org and https://impin.fr analytics.
See it in action at https://next-impin.vercel.app, and this commit for a real world example.
To enable Impin analytics in your Next.js app you'll need to expose the Impin context, <ImpinProvider />, at the top level of your application inside _app.js:
// pages/_app.js
import ImpinProvider from 'next-impin'
export default function MyApp({ Component, pageProps }) {
return (
<ImpinProvider domain="example.com">
<Component {...pageProps} />
</ImpinProvider>
)
}If you want to enable Impin analytics only on a single page you can wrap the page in a ImpinProvider component:
// pages/home.js
import ImpinProvider from 'next-impin'
export default Home() {
return (
<ImpinProvider domain="example.com">
<h1>My Site</h1>
{/* ... */}
</ImpinProvider>
)
}If are using the app directory include ImpinProvider inside the root layout:
// app/layout.js
import ImpinProvider from 'next-impin'
export default function RootLayout({ children }) {
return (
<html>
<head>
<ImpinProvider domain="example.com" />
</head>
<body>{children}</body>
</html>
)
}| Name | Description |
|---|---|
domain |
The domain of the site you want to monitor. |
customDomain |
Set this if you use a custom domain to serve the analytics script. Defaults to https://impin.fr. See https://impin.fr/docs/custom-domain for more details. |
trackOutboundLinks |
Set this to true if you want to enable outbound link click tracking. |
trackFileDownloads |
Set this to true if you want to enable file download tracking. |
taggedEvents |
Set this to true if you want to enable custom event tracking in HTML elements. |
trackLocalhost |
Set this to true if you want to enable localhost tracking. |
manualPageviews |
Set this to true if you want to disable automatic pageview events. |
pageviewProps |
Set the custom properties for pageviews. The event- prefix will be added automatically. See an example. |
revenue |
Set this to true if you want to enable ecommerce revenue tracking. |
hash |
Set this to true if you want to use hash-based routing. |
exclude |
Set this if you want to exclude a set of pages from being tracked. See https://impin.fr/docs/excluding-pages for more details. |
selfHosted |
Set this to true if you are self hosting your Impin instance. Otherwise you will get a 404 when requesting the script. |
enabled |
Use this to explicitly decide whether or not to render script. If not passed the script will be rendered in production environments (checking NODE_ENV and VERCEL_ENV). |
integrity |
Optionally define the subresource integrity attribute for extra security. |
scriptProps |
Optionally override any of the props passed to the script element. See example. |
To avoid being blocked by adblockers impin recommends proxying the script. To do this you need to wrap your next.config.js with the withImpinProxy function:
const { withImpinProxy } = require('next-impin')
module.exports = withImpinProxy()({
// ...your next js config, if any
// Important! it is mandatory to pass a config object, even if empty
})This will set up the necessary rewrites as described here and configure ImpinProvider to use the local URLs so you can keep using it like this:
<ImpinProvider domain="example.com">
...
</ImpinProvider>
}Optionally you can overwrite the proxied script subdirectory and name, as well as the custom domain for the original script:
const { withImpinProxy } = require('next-impin')
module.exports = withImpinProxy({
subdirectory: 'yoursubdirectory',
scriptName: 'scriptName',
customDomain: 'http://example.com',
})({
// ...your next js config, if any
// Important! it is mandatory to pass a config object, even if empty
})This will load the script from /yoursubdirectory/js/scriptName.js and fetch it from http://example.com/js/script.js.
Notes:
-
Proxying will only work if you serve your site using
next start. Statically generated sites won't be able to rewrite the requests. -
If you are self hosting impin, you need to set
customDomainto your instance otherwise no data will be sent. -
Bear in mind that tracking requests will be made to the same domain, so cookies will be forwarded. See https://github.com/Impin-team/next-impin/issues/67. If this is an issue for you, from
next@13.0.0you can use middleware to strip the cookies like this:import { NextResponse } from 'next/server' export function middleware(request) { const requestHeaders = new Headers(request.headers) requestHeaders.set('cookie', '') return NextResponse.next({ request: { headers: requestHeaders, }, }) } export const config = { matcher: '/proxy/api/event', }
Impin supports custom events as described at https://impin.fr/docs/custom-event-goals. This package provides the useImpin hook to safely access the impin function like this:
import { useImpin } from 'next-impin'
export default function ImpinButton() {
const impin = useImpin()
return (
<>
<button onClick={() => impin('customEventName')}>Send</button>
<button
id="foo"
onClick={() =>
impin('customEventName', {
props: {
buttonId: 'foo',
},
})
}
>
Send with props
</button>
</>
)
}If you use Typescript you can type check your custom events like this:
import { useImpin } from 'next-impin'
type MyEvents = {
event1: { prop1: string }
event2: { prop2: string }
event3: never
}
const impin = useImpin<MyEvents>()Only those events with the right props will be allowed to be sent using the impin function.
-
npm run buildwill generate the production scripts under thedistfolder.