Web SDK Quickstart¶

This guide provides a detailed tutorial on integrating the Superfine JavaScript SDK (Web-SDK) into your project. Ensure you have the necessary credentials before you begin.

1. Configure Project (detail)¶

To use the Web-SDK, you need specific project configuration details from the Superfine Platform. Here's how to get them:

Navigate to the Project Settings page on the Superfine Platform.
Select your project and note the Project ID and Project Secret from the Project details page.

ProjectBasicSetup

2. Installation¶

To load the SDK via HTTP, add the following snippet between your web app's <head> tags:

<script type="text/javascript">
  !function(e,o,n,t,l,i,g,r,s,a,p,k){var L=g+"_q";e[g]=e[g]||{},e[L]=e[L]||[];for(var d=0;d<r.length;d++)a(e[g],e[L],r[d]);for(const o in s)e[g][o]=s[o];p=o.createElement(n),k=o.getElementsByTagName(n)[0],p.async=!0,p.src="https://static.superfine.org/sdk/superfine-sdk-0.0.15.1.min.js",i&&(p.crossOrigin="anonymous",p.integrity=i),p.onload=function(){for(var o=0;o<e[L].length;o++)e[g][e[L][o][0]].apply(e[g],e[L][o][1]);e[L]=[]},k.parentNode.insertBefore(p,k)}(window,document,"script",0,0,"sha384-Ouy3JW7NGTIk/sB+LSNFc6FbCioUHfv5SXgJffK3tV6/2usNwNLUlXrKJA6Tizzl","SuperfineSDK",["setLogger","setLogLevel","setLogTag","initialize","isInitialized","shutdown","getVersion","registerModule","unregisterModule","getDeepLinkUrl","openURL","getPushToken","setPushToken","addStartListener","removeStartListener","addStopListener","removeStopListener","addPauseListener","removePauseListener","addResumeListener","removeResumeListener","addSendEventListener","removeSendEventListener","addDeepLinkListener","removeDeepLinkListener","addPushTokenListener","removePushTokenListener","start","stop","logThirdPartySettingsSharing","getUserId","getFacebookAppId","getInstagramAppId","getAppleAppId","getAppleSignInClientId","getAppleDeveloperTeamId","getGooglePlayGameServicesProjectId","getGooglePlayDeveloperAccountId","getLinkedInAppId","getQQAppId","getWeChatAppId","setConfigId","setCustomUserId","logBootStart","logBootEnd","logLevelStart","logLevelEnd","logAdLoad","logAdClick","logAdClose","logAdImpression","logIAPInitialization","logIAPRestorePurchase","logIAPResult","logIAPReceipt_Apple","logIAPReceipt_Google","logIAPReceipt_Amazon","logIAPReceipt_Roku","logIAPReceipt_Windows","logIAPReceipt_Facebook","logIAPReceipt_Unity","logIAPReceipt_AppStoreServer","logIAPReceipt_GooglePlayProduct","logIAPReceipt_GooglePlaySubscription","logIAPReceipt_GooglePlaySubscriptionv2","logUpdateApp","logRateApp","logLocation","logAutoLocation","logAccountLink","logAccountUnlink","logFacebookLink","logFacebookUnlink","logInstagramLink","logInstagramUnlink","logAppleLink","logAppleUnlink","logAppleGameCenterLink","logAppleGameCenterTeamLink","logAppleGameCenterUnlink","logGoogleLink","logGoogleUnlink","logGooglePlayGameServicesLink","logGooglePlayGameServicesDeveloperLink","logGooglePlayGameServicesUnlink","logLinkedInLink","logLinkedInUnlink","logMeetupLink","logMeetupUnlink","logGitHubLink","logGitHubUnlink","logDiscordLink","logDiscordUnlink","logTwitterLink","logTwitterUnlink","logSpotifyLink","logSpotifyUnlink","logMicrosoftLink","logMicrosoftUnlink","logLINELink","logLINEUnlink","logVKLink","logVKUnlink","logQQLink","logQQUnlink","logWeChatLink","logWeChatUnionLink","logWeChatUnlink","logTikTokLink","logTikTokUnionLink","logTikTokUnlink","logWeiboLink","logWeiboUnlink","addUserPhoneNumber","removeUserPhoneNumber","addUserEmail","removeUserEmail","setUserName","setUserCity","setUserState","setUserCountry","setUserZipCode","setUserDateOfBirth","setUserGender","logWalletLink","logWalletUnlink","logCryptoPayment","logAdRevenue","logWithNumber","logWithString","logWithMap","log"],{AdPlacement:{UNKNOWN:"",BOTTOM:"bottom",TOP:"top",LEFT:"left",RIGHT:"right",FULL_SCREEN:"fullscreen"},AdPlacementType:{BANNER:"banner",INTERSTITIAL:"interstitial",REWARDED_VIDEO:"rewarded_video"},StoreType:{UNKNOWN:"other",APP_STORE:"app_store",GOOGLE_PLAY:"google_play",AMAZON_STORE:"amazon_store",MICROSOFT_STORE:"microsoft_store"},LogLevel:{OFF:0,ERROR:1,WARN:2,INFO:3,DEBUG:4,VERBOSE:5},UserGender:{MALE:"male",FEMALE:"female"}},(function(e,o,n){e[n]=function(){o.push([n,arguments])}}));
</script>

3. Initialize SDK¶

Once you've installed the SDK, you need to initialize it. To do this, call the SuperfineSDK.initialize method. This method takes several parameters that customize how the SDK works in your app.

You must add the following arguments to your SuperfineSDK.initialize call to initialize the SDK:

YOUR_PROJECT_ID: Your Project ID from the Configure Project step.
YOUR_PROJECT_SECRET: Your Project Secret from the Configure Project step.

// Optional
const initConfigs = {
    autoStart: true,
    flushAt: 5,
    flushInterval: 1000,
    enableAttribution: true,
  // ...other configs
}
SuperfineSDK.initialize('YOUR_PROJECT_ID', 'YOUR_PROJECT_SECRET', initConfigs)

Note: If you are using Pixel or Google Tag, please add an event callback function to ensure events are forwarded to the ad network.

  // Adding listener
  SuperfineSDK.addSendEventListener(onSendEvent);

  // Initialize Superfine SDK
  SuperfineSDK.initialize('YOUR_PROJECT_ID', 'YOUR_PROJECT_SECRET',{});

  // Event callback
  function onSendEvent(eventName, eventData) {
      sendAdNetworkEvent(eventName, eventData);
  }
  function sendAdNetworkEvent(eventName, eventData) {
    if (eventName === 'gjsdk_iap_success_payment') {
        // Passing events to Pixel - Meta
        fbq('track', "Purchase", {currency: eventData.currency, value: eventData.price * eventData.amount});
        // Passing events to Google
        gtag('event', "purchase", {
            transaction_id: eventData.pack,
            value: eventData.price,
            currency: eventData.currency,
            quantity: eventData.amount
        });
    } else {
        // Passing events to Pixel - Meta
        fbq('trackCustom', eventName, eventData);
        // Passing events to Google
        gtag('event', eventName, eventData);
    }
  }

4. Sending events¶

With Superfine, you can send various web events for conversions or other relevant activities on your website. Below are methods for different event types:

4.1 Linking Event¶

logAccountLink:¶

logAccountLink(id: string, type: string): void

Description: Call these methods when you want to link the user with another identity.

Parameters
`id`	string: can't be null. This is your user ID.
`type`	string: can't be null. Type of identity. Supports "email", "facebook", "twitter", etc.

Example:

SuperfineSDK.logAccountLink("test@superfine.org", "superfine")

We also support various functions:

logFacebookLink(userId: string): void
logInstagramLink(userId: string): void
logAppleLink(userId: string): void
logAppleGameCenterLink(gamePlayerId: string): void
logAppleGameCenterTeamLink(teamPlayerId: string): void
logGoogleLink(userId: string): void
logGooglePlayGameServicesLink(gamePlayerId: string): void
logGooglePlayGameServicesDeveloperLink(developerPlayerKey: string): void
logLinkedInLink(personId: string): void
logMeetupLink(userId: string): void
logGitHubLink(userId: string): void
logDiscordLink(userId: string): void
logTwitterLink(userId: string): void
logSpotifyLink(userId: string): void
logMicrosoftLink(userId: string): void
logLINELink(userId: string): void
logVKLink(userId: string): void
logQQLink(userId: string): void
logWeChatLink(userId: string): void
logWeChatUnionLink(unionId: string): void
logTikTokLink(userId: string): void
logTikTokUnionLink(unionId: string): void
logWeiboLink(userId: string): void

logAccountUnlink:¶

logAccountUnlink(type: string): void

Description: Call this method when you want to unlink the user with external identity.

Parameters
`type`	String: can't be null. Type of identity. Supports "email", "facebook", "twitter", etc.

Example:

SuperfineSDK.logAccountUnlink("superfine")

We also support various functions:

logFacebookUnlink(): void
logInstagramUnlink(): void
logAppleUnlink(): void
logAppleGameCenterUnlink(): void
logGoogleUnlink(): void
logGooglePlayGameServicesUnlink(): void
logLinkedInUnlink(): void
logMeetupUnlink(): void
logGitHubUnlink(): void
logDiscordUnlink(): void
logTwitterUnlink(): void
logSpotifyUnlink(): void
logMicrosoftUnlink(): void
logLINEUnlink(): void
logVKUnlink(): void
logQQUnlink(): void
logWeChatUnlink(): void
logTikTokUnlink(): void
logWeiboUnlink(): void

linkWallet:¶

logWalletLink(wallet: string, type: string = 'ethereum'): void

Description: Call this method when you want to link the user's wallet address.

Parameters
`wallet`	String: can't be null. The wallet address you want to log the linking event for.
`type`	String: Default is Ethereum. Type of the wallet (optional).

Example:

SuperfineSDK.logWalletLink("0x50460c4cd74094cd591455cad457e99c4ab8be0", 'eth')

unlinkWallet:¶

logWalletUnlink(wallet: string, type: string = 'ethereum')

Description: Call this method when you want to unlink the user's wallet address.

Parameters
`wallet`	String: can't be null. The wallet address you want to log the linking event for.
`type`	String: Default is Ethereum. Type of the wallet (optional).

Example:

SuperfineSDK.logWalletUnlink("0x50460c4cd74094cd591455cad457e99c4ab8be0", 'eth')

4.2 Revenue Event¶

logAdRevenue:¶

logAdRevenue(source: string, revenue: number, currency: string, network: string = '', networkData: JSONObject | null = null): void

Description: Call this function to send ad revenue.

Parameters
`source`	String: Can’t be null. The ID of the purchase.
`revenue`	Number: Can’t be null. Revenue from ads.
`currency`	String: Can’t be null. The currency code (e.g., "USD", "EUR") for the price.
`network`	String: Default is empty. The network name (optional).
`networkData`	JSONObject or null: Default is null. The network data (optional).

Example:

SuperfineSDK.logAdRevenue("Add network", 0.01, 'USD', 'native', {
  param1: '123',
  param2: '456',
  param3: 0.0000000000000001,
  param4: 123456789123456789,
})

4.3 Custom Event¶

log:¶

log(eventName: string, value: JSONObject | null = null, flag: number = 0): void

Description: Call this function to send your custom events.

Parameters
`eventName`	String: Can’t be null. The name of your event.
`value`	JSONObject or null: Default is null. Any data object you want to store within this event.
`flag`	Number: Default is 0. Flag of the event. Supports (NONE: 0), (OPEN: 1), (FORCE DISABLE: 2), (WAIT OPEN EVENT: 4), (CACHE: 8).

Example:

SuperfineSDK.log('btn_click', { param1: 1, param2: ['1', '2'] })

We also support various functions:

logWithNumber(eventName: string, value: number, flag: number = 0): void
logWithString(eventName: string, value: string, flag: number = 0): void
logWithMap(eventName: string, value: Record<string, string>, flag: number = 0): void

4.4 User Info¶

addUserPhoneNumber:¶

addUserPhoneNumber(countryCode: number, number: string): void

Description: Call this function to add user phone number.

Parameters
`countryCode`	Number: Can’t be null. The country code.
`number`	String: Can’t be null. The phone number.

Example:

SuperfineSDK.addUserPhoneNumber(1, "555-5555")

removeUserPhoneNumber:¶

removeUserPhoneNumber(countryCode: number, number: string): void

Description: Call this function to remove user phone number.

Parameters
`countryCode`	Number: Can’t be null. The country code.
`number`	String: Can’t be null. The phone number.

Example:

SuperfineSDK.removeUserPhoneNumber(1, "555-5555")

addUserEmail:¶

addUserEmail(email: string): void

Description: Call this function to add user email.

Parameters
`email`	String: Can’t be null. The email of the user.

Example:

SuperfineSDK.addUserEmail("test@mail.com")

removeUserEmail:¶

removeUserEmail(email: string): void

Description: Call this function to remove user email.

Parameters
`email`	String: Can’t be null. The email of the user.

Example:

SuperfineSDK.removeUserEmail("test@mail.com")

setUserName:¶

setUserName(firstName: string, lastName: string): void

Description: Call this function to set name of the user.

Parameters
`firstName`	String: Can’t be null. The first name of the user.
`lastName`	String: Can’t be null. The last name of the user.

Example:

SuperfineSDK.setUserName("John", "Doe")

setUserCity:¶

setUserCity(city: string): void

Description: Call this function to set city of the user.

Parameters
`city`	String: Can’t be null. The city name of the user.

Example:

SuperfineSDK.setUserCity("CITY")

setUserState:¶

setUserState(state: string): void

Description: Call this function to set state of the user.

Parameters
`state`	String: Can’t be null. The state of the user.

Example:

SuperfineSDK.setUserState("STATE")

setUserCountry:¶

setUserCountry(country: string): void

Description: Call this function to set country of the user.

Parameters
`country`	String: Can’t be null. The country of the user.

Example:

SuperfineSDK.setUserCountry("Country")

setUserZipCode:¶

setUserZipCode(zipCode: string): void

Description: Call this function to set zip code of the user.

Parameters
`zipCode`	String: Can’t be null. The zip code of the user.

Example:

SuperfineSDK.setUserZipCode("Country")

setUserDateOfBirth:¶

setUserDateOfBirth(day?: number, month?: number, year?: number): void

Description: Call this function to set date of birth of the user.

Parameters
`day`	Number: Default is null. The user's day of birth.
`month`	Number: Default is null. The user's month of birth.
`year`	Number: Default is null. The user's year of birth.

Example:

SuperfineSDK.setUserDateOfBirth(1, 1, 2000)