SDK for Unity on Android

Luminati SDK can be used for Android applications written with Unity framework.

This document assumes that you have the following software installed:

Sample test_vpn_api application:

  • Contact us to get a sample project
  • Unzip it on your local drive
  • Open the project with Unity by double-clicking the scene.unity file in Assets folder

Launch Android emulator:
  • Open console and go to your Android SDK folder
  • Navigate to tools subdirectory
  • Execute android list avd - this will output a list of created devices
  • If the list is empty and it's your first run then execute android avd and create a new device using GUI
  • Execute emulator -avd [device name]substituting a required device name from the list - this command launches an emulator with a selected device
Launch the sample application:
  • In Unity, select menu item File/Build & Run
  • Select Android in the platforms list and click Build And Run
  • If a dialog menu appears, choose where to save the apk file
  • After several seconds, you should see an application launched in your opened emulator window
Clicking on a Launch SDK button shows the usage agreement. Here, a user is able to select application pricing plan.

Adding SDK initialization code to existing application:

  • Contact usto get Luminati SDK for Unity
  • Extract topvpn_vpn_api.aar and topvpn_vpn_api.dll files to Assets folder of your Unity project
  • The required namespace (add it to the main MonoBehaviour class of your application):
    using io.topvpn.vpn_api;
  • Add this call to your Start() method:
    api.init(false);
    It will show an agreement popup on a first run of application.
    User's choice will be remembered and the popup won't appear on subsequent application launches.

    If you want to let user change his choice (e.g., on a special button click in settings menu), call this method with true as argument.

API description:

  • You'll be able to retrieve user's choice (on later runs as well) by calling this method:
    api.get_user_selection();
    It returns an int, one of:
    • 0 - NONE (when user didn't select any option yet, or if api.clear_selection() was called)
    • 1 - FREE (idle resources are used by SDK)
    • 2 - ADS (user agrees to watch advertisements - note that ads are not provided by SDK)
    • 3 - SUBSCRIPTION (user pays for using your app)
    • 4 - NOT_PEER (this meaning is customizable, see set_btn_not_peer_txt method below)
    These values are enumerated in api.CHOICE.

    Example:
    Before loading each level of a game, a splash screen is shown.
    For users who selected ADS plan, an advertisement is placed on this screen.
    For others, a predefined level picture is chosen.
    A function that returns a path to splash screen image can be implemented like this:
    public string get_level_loading_image(int level){
      if (api.get_user_selection()==2) // 2 - ADS
          return get_random_banner();
      else
          return LEVEL_IMAGES[level];
  • You may want to be notified when users makes his choice of plan. If that's the case then a listener should be added before a call to api.init:
    void Start(){
      api.set_selection_listener(choice=>Debug.Log("User selected "+api.CHOICE[choice]));
      api.init(false);
    }
  • This method allows to clear user's choice remembered after a call to api.init. Also, it turns off the SDK(you can re-enable it again by calling api.init).
    api.clear_selection();
    Useful for disabling peer mode from user options.
    Selection listener will be triggered with value NONE.
The following functions allow to customize agreement popup appearance:
  • The dialog type:
    api.set_dialog_type(api.DIALOG_TYPE.PEER1);
    api.DIALOG_TYPE is enum containing predefined dialog types:
    • PEER1 type asks whether device idle resources usage is allowed (default). Choice returned may be eitherFREE (use idle resources) orNOT_PEER (monetization SDK is not used).
    • CHOOSE type provides three radio buttons:
      • FREE - use idle resources
      • ADS - show ads (advertisements are not provided by SDK)
      • SUBSCRIPTION - paid application usage
    • PEER2 type unconditionally warns a user that idle resources of device would be utilized (deprecated). A call to get_user_selection() returns FREE in this case.
  • Set caption of "PEER" button (available only for PEER1 dialog type):
    api.set_btn_peer_txt(api.BTN_PEER_TXT.I_AGREE);
    api.BTN_PEER_TXT is enum with predefined captions for the button returning choice FREE.
    The test_vpn_api sample application allows to customize dialog type and button captions. See it as quick interactive reference.
    Available values:
    • NO_ADS
    • PREMIUM
    • FREE
    • DONATE
    • I_AGREE
  • Set caption of "NOT_PEER" button (available only for PEER1 dialog type):
    api.set_btn_not_peer_txt(api.BTN_NOT_PEER_TXT.NOT_AGREE);
    api.BTN_NOT_PEER_TXT is enum with predefined captions for the button returning choice NOT_PEER.
    Available values:
    • ADS
    • LIMITED
    • PREMIUM
    • NO_DONATE
    • NOT_AGREE

  • The new agree screen (PEER1) allows the user to choose between opt-in/out of using the SDK. You just need to select the text for the buttons that best describe what each selection means for the user/you.

    For example, if using the SDK gives the user extra features then you should select PREMIUM for peer and LIMITED for not peer, or if using the SDK gives no benefits except additional income for you then you should choose DONATE and NO_DONATE accordingly.

  • Set background color for the top dialog rectangle (available only for PEER2 dialog type), use hexademical integer representation of color ARGB components:
    api.set_top_background(0xFF00FF00); // green
  • Set background color for the bottom dialog rectangle (available only for PEER2 dialog type):
    api.set_bottom_background(0xFF0000FF); // blue
  • Set whether a standard Luminati service level agreement (SLA) text should be shown (available only for PEER2dialog type):
    api.set_sla_link(false);
    Setting it to false allows to replace the agreement text with your custom link using next method.

    Note that set_hola_sla_link method is deprecated. Use set_sla_link instead.
  • Set a link to terms of service (TOS) text (available only for PEER1 and PEER2 dialog types):
    api.set_tos_link("http://mygame.mydomain.com/tos.html");

  • Example:
    Customizing popup dialog appearance before showing it on application start:
    void Start(){
      api.set_tos_link("http://mygame.mydomain.com/tos.html");
      api.set_dialog_type(api.DIALOG_TYPE.PEER1);
      api.set_btn_peer_txt(api.BTN_PEER_TXT.FREE);
      api.set_btn_not_peer_txt(api.BTN_NOT_PEER_TXT.PREMIUM);
      api.set_selection_listener(choice=>{
          // Psuedocode for handling user selection (not mandatory,
          // can use api.get_user_selection directly instead)
          switch(choice){
          case 1: // FREE
              settings.set_luminati_sdk_used(true);
              break;
          case 0: // NONE
          case 4: // NOT_PEER
              settings.set_luminati_sdk_used(false);
              break;
          }
      });
      api.init(false);
    }