Harmony Preparation

Development Environment Requirements

• DevEco Studio: Latest version recommended
• HarmonyOS SDK: HarmonyOS 2.0 or higher
• Java: Java 8 or higher
• Node.js: 12.0 or higher

Project Configuration

1. Add Dependencies

Add UJU Ad SDK dependencies to your build.gradle file:

dependencies {
    // UJU core SDK
    implementation 'com.ujusdk:harmony-sdk:1.0.0'
    
    // Optional adapters
    implementation 'com.ujusdk:harmony-csj-adapter:1.0.0'
    implementation 'com.ujusdk:harmony-gdt-adapter:1.0.0'
}

2. Configure config.json

Add necessary configurations to config.json file:

{
  "app": {
    "bundleName": "com.example.app",
    "vendor": "example",
    "version": {
      "code": 1000000,
      "name": "1.0.0"
    },
    "apiVersion": {
      "compatible": 3,
      "target": 3
    }
  },
  "deviceConfig": {
    "default": {
      "orientation": "unspecified",
      "network": {
        "cleartextTraffic": true
      }
    }
  },
  "module": {
    "package": "com.example.app",
    "name": ".App",
    "mainAbility": "com.example.app.MainAbility",
    "deviceTypes": ["phone", "tablet"],
    "distro": {
      "deliveryWithInstall": true,
      "moduleName": "entry",
      "moduleType": "entry",
      "installationFree": false
    },
    "abilities": [
      {
        "name": "com.example.app.MainAbility",
        "srcEntry": "ets/mainability/MainAbility.ts",
        "description": "Main ability",
        "icon": "$media:icon",
        "label": "App",
        "type": "page",
        "visible": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ]
  }
}

3. Configure Permissions

Add necessary permissions to module.json5 file:

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "Needed for ad network connections",
        "usedScene": {
          "ability": ["com.example.app.MainAbility"],
          "when": "always"
        }
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "reason": "Needed for network status detection",
        "usedScene": {
          "ability": ["com.example.app.MainAbility"],
          "when": "always"
        }
      }
    ]
  }
}

SDK Initialization

Initialize the SDK in your MainAbility class:

import com.ujusdk.harmony.UjuAdSDK;
import com.ujusdk.harmony.UjuAdInitConfig;
import com.ujusdk.harmony.callback.InitCallback;

public class MainAbility extends Ability {
    @Override
    public void onStart(Intent intent) {
        super.onStart(intent);
        
        // Initialize UJU SDK
        initializeUjuSDK();
        
        super.setMainRoute(MainAbilitySlice.class.getName());
    }
    
    private void initializeUjuSDK() {
        UjuAdInitConfig config = new UjuAdInitConfig.Builder()
            .setAppId("YOUR_APP_ID")
            .setAppKey("YOUR_APP_KEY")
            .setDebugMode(true)
            .build();
        
        UjuAdSDK.init(this, config, new InitCallback() {
            @Override
            public void onSuccess() {
                // SDK initialized successfully
                HiLog.info(new HiLogLabel(HiLog.LOG_APP, 0x00001, "UjuSDK"), "UJU SDK initialized successfully");
            }
            
            @Override
            public void onFailure(String error) {
                // SDK initialization failed
                HiLog.error(new HiLogLabel(HiLog.LOG_APP, 0x00001, "UjuSDK"), "UJU SDK initialization failed: %{public}s", error);
            }
        });
    }
}

Testing

Test Mode

Enable test mode during development:

// Enable test mode
UjuAdSDK.setTestMode(true);

Test Devices

Add test devices to avoid invalid clicks:

// Add test device
UjuAdSDK.addTestDevice("YOUR_DEVICE_ID");

Best Practices

• Early initialization: Initialize the SDK as early as possible in the application startup process
• Permission handling: Request necessary permissions before loading ads
• Error handling: Implement proper error handling for ad loading failures
• Ad preloading: Preload ads before they need to be displayed
• Frequency control: Control ad display frequency to avoid user annoyance

Common Questions

Q: Why isn't the SDK initializing?

A: Possible reasons:

• Incorrect App ID or App Key
• Network connection issues
• HarmonyOS version incompatibility
• Missing required permissions

Q: What permissions are required for Harmony ads?

A: Required permissions:

• ohos.permission.INTERNET: For network access
• ohos.permission.GET_NETWORK_INFO: For network status detection

Optional permissions:

• ohos.permission.LOCATION: For better ad targeting

Next Steps

After completing the preparation work, you can proceed with:

• SDK Initialization
• Ad Type Integration