# nw-attribution

> 渠道归因前端SDK

Latest version **2.15.0** (published 2023-10-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install nw-attribution
pnpm add nw-attribution
yarn add nw-attribution
bun add nw-attribution
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.15.0 |
| Published | 2023-10-25 |
| First published | 2020-06-01 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 9 |
| Unpacked size | 212.1 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | hzliushichuan@corp.netease.com |
| Maintainers | luofeiyue, whiskeyi, yousy, guoyeeg, azgaga, liushichuan, yaochen, shenyuan, aflyermin, ignous, jeekdong |
| Keywords | lofter |

## Links

- npm: https://www.npmjs.com/package/nw-attribution
- npm.io page: https://npm.io/package/nw-attribution

## Dependencies (9)

- [uuid](https://npm.io/package/uuid.md) ^8.3.1
- [core-js](https://npm.io/package/core-js.md) ^3.16.0
- [shortid](https://npm.io/package/shortid.md) ^2.2.15
- [clipboard](https://npm.io/package/clipboard.md) ^2.0.6
- [query-string](https://npm.io/package/query-string.md) ^6.12.1
- [ua-parser-js](https://npm.io/package/ua-parser-js.md) ^0.7.21
- [clipboard-copy](https://npm.io/package/clipboard-copy.md) ^3.2.0
- [fingerprintjs2](https://npm.io/package/fingerprintjs2.md) ^2.1.0
- [clipboard-polyfill](https://npm.io/package/clipboard-polyfill.md) ^2.8.6

## Recent versions

- 2.15.0 (latest) — 2023-10-25
- 2.14.0 — 2022-12-05
- 2.13.0 — 2022-12-05
- 2.12.1 — 2022-08-31
- 2.12.0 — 2022-06-15
- 2.11.2 — 2022-05-05
- 2.11.1 — 2021-08-09
- 2.11.0 — 2021-08-05
- 2.10.1 — 2021-07-08
- 2.10.0 — 2021-07-08
- 2.9.0 — 2021-07-07
- 2.8.3 — 2021-07-07
- 2.7.0 — 2020-12-11
- 2.2.3 — 2020-11-11
- 2.1.0 — 2020-11-10
- … 3 more at https://npm.io/package/nw-attribution/versions

## README

# nw-attribution

> 渠道归因SDK

## 原理
1. 本SDK主要是根据随机生成的uuid组成设备的唯一token（设备指纹碰撞率太高，尤其IOS端，不再计算）
2. 再自动获取H5页面的URL中的`channel`和`uid`信息，得到渠道信息和分享人信息
3. 本SDk还会收集URL中`channel`、`uid`以外的其他信息，最终结合手动传入的`extraData`作为全部的收集信息进行上报
4. 提供2个方法，可以选择自动跳转到官网最新渠道包下载，也可以不下载只获取上报URL，自行处理上报逻辑

## 安装

```sh
$ npm install nw-attribution --save
```

## 注意事项
- 如果要收集渠道信息，页面的URL query中需用`channel`设置对应的渠道信息，比如：`https://www.lofter.com/test.html?channel=banner1`
- 如果URL中缺少`channel`字段，可以通过传入`overwriteChannel`字段来覆盖URL中的`channel`
- 如果要收集分享人信息，页面的URL query中需用`uid`设置对应的分享人userId，比如：`https://www.lofter.com/test.html?uid=123`
- URL中`channel`、`uid`外的其他信息，也会被自动收集，作为`extraData`的一部分
- 如果当前页面还有一些需要代码计算，无法固化在URL中的附加信息，可以自行收集后通过`extraData`上报，最终会与URL中的其他信息综合在一起，比如URL中含有`testValue=1`，手动传入了`myUserId=2`，最终会组成`testValue=1&myUserId=2`的上报信息
- 因为受浏览器安全限制，想要将文本自动复制到用户剪切板，**必须有用户的直接点击操作**，所以必须在初始化SDk时，传入将会触发点击的DOM元素，才能利用剪切板完成本次归因信息收集
- 页面的URL query中使用`incantation`设置对应的口令信息，比如：`https://www.lofter.com/test.html?incantation=banner1`

## 使用

- es6方式引用
```html
<button id="download">点我下载</button>
```
```javascript
import Attributon from 'nw-attribution';
const extraData = `testValue=testKey`; // 想要额外上报的信息，字符串格式,
const btn = document.querySelector('#download');

// 初始化SDK
const attribution = new Attributon({
  button: btn,
  extraData,
})

// 直接拷贝token到剪切板并跳转上报下载url
btn.addEventListener('click', () => {
  log.sendLog('a1-1')
  // 延时300ms，并且自动上报然后跳转下载
  attribution.attributionDownload(300);
})

// 拷贝token到剪切板，传递callback获取url
btn.addEventListener('click', () => {
  attributionUrl({
    extraData,
    noDownload: true,
    callback: url => {
      console.log(url);
    }
  })
})
```

- browser中直接使用（需要拷贝后bundle.js）
```html
<script src="./bundle.js"></script>
<script>
  var btn = document.querySelector('#btn');
  var attribution = new NWAttribution.default({
    button: app
  });
  btn.addEventListener('click', function () {
    attribution.attributionDownload(300);
    console.log('click');
    // do something such as send a log
  })
  btn.addEventListener('click', () => {
    NWAttribution.attributionDownload({
      useCache: false,
      extraData: 'test=1',
      downloadTimeout: 2000
    });
    //NWAttribution.attributionUrl({
    //  useCache: true,
    //  extraData: 'test=1',
    //  callback: function (url) {
    //    console.log('url', url);
    //  }
    });
  })
</script>
```

## 发布
1. 在根目录运行`npm run build nw-attribution`打包es module格式的代码
2. 在当前`packages/nw-attribution`目录下运行`npm run build`打包UMD格式的代码
3. 提交Git信息
4. 在根目录运行`npm run onlyPublish`，发布组件更新

## API

<a name="track"></a>

## track() ⇒ <code>Promise.&lt;void&gt;</code>
**Kind**: global function

---
_Source: https://npm.io/package/nw-attribution · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._