Prerequisites

2025-04-24 03:36

Android

Step 1：Add Rewards SDK to your project

copy
dependencies {
    // Required, Marketing Basic Library
    implementation 'com.alipay.plus.android.marketing:marketing:LATEST_VERSION
    // Required, widget render Library
    implementation 'com.alipay.plus.tiny.dynamic:dynamic_widget_sdk:LATEST_VERSION’

    // Optional. Non-Alipay+ SDK containers need to be added, but Alipay+ SDK container does not need to be added
    implementation 'com.alipay.plus.android.marketingFoundation:marketingFoundation:LATEST_VERSION
}

Step 2：Add warehouse address in settings. gradle

copy
pluginManagement {
    repositories {
        ......
        mavenCentral()
        maven {
            credentials {
                username "iapsdkdownload@gmail.com"
                password "1Download"
            }
            url 'https://globaltech.alipay.com/api/v1/file/repository/minisdk/'
        }
    }
}
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        ......
        mavenCentral()
        maven {
            credentials {
                username "iapsdkdownload@gmail.com"
                password "1Download"
            }
            url 'https://globaltech.alipay.com/api/v1/file/repository/minisdk/'
        }
    }
}

Step 3：Initialize rewards

copy
// import A+ marketing module
import com.iap.ac.android.marketing.PromoManager;
import com.iap.ac.android.marketing.PromoInitConfig;


// init A+ marketing module，Need to be placed after initializing the container
PromoInitConfig promoConfig = new PromoInitConfig();
// The build environment must be configured as PROD
promoConfig.envType = "DEV";
promoConfig.getInstance().initWithPromoInitConfig(context, promoConfig);

Step 4：Add a New Configuration File

Contact the point of contact to provide the file

Add a new configuration file named rewards_widget_config.json and place it in the path: App/assets.

copy
{
    "auth": {
        "type": "mini-program", // environment type
        "clientId": "xxx",          // pass it to merchant as clientId/authClientId and get the auth code
        "scope": "auth_base",   // usually it's auth_base, it means only get user Id
        "mpContext": {                  // mpContext is required only when the type is miniprogram.
          "appId": "xxx",           // mini-app ID
          "merchantId": "xxx",  // merchant ID provider from mini-program platform, check this: https://yuque.antfin-inc.com/ac/xbggo2/imno85pm4or4hfzz#BVbGs
          "name": "xxxx",           // mini-app name
          "logo": "xxx",                // mini-app logo
          "desc": "xxx",                // mini-app desc
          "deployVersion": "xxx",   // mini-app version, you can get it from platform. like: v3.47.807
          "developerVersion": "xxx" // mini-app version of development stage, you can get it from IDE. like: v3.47.807.1728550147
        }
    },
    "rpc":{
          "appId": "MY_APP_ID",
          "gatewayUrl": {
              "dev": "DEV_GATEWAY_URL",  // dev gateway address
              "sit": "SIT_GATEWAY_URL",  // sit gateway address
              "pre": "PRE_GATEWAY_URL",  // pre gateway address
              "prod": "PROD_GATEWAY_URL" // prod gateway address
          }
    },
    adapter:{
        "type":"XXX"  // adapter type
    }
}

Step 5: Clear login state

This function is called during logout to clear the user cache and reset the login status. If this function is not configured, it may result in an abnormal contract status, and the data loaded will still be associated with the previous user

copy
PromoManager.getInstance().clear()

Step 6: Config JSAPI

Alipay+ SDK container

jsapi has been registered internally, no need to implement it here

Non-Alipay+ SDK container

This only needs to be implemented when it is not a Alipay+ SDK container

1): Users are required to register the container's jspai

2): To facilitate communication between the container jsapi and the MarketingFoundationSDK, you must act as an intermediary by managing the communication within the registered jsapi callback.

Example:

copy
//1.register jsApi
 WVPluginManager.registerPlugin("AlipayPlusJsapiHandle", MarketingJsapiHandle.class);

public class MarketingJsapiHandle extends WVApiPlugin {
    @Override
    protected boolean execute(String action, String params, WVCallBackContext wvCallBackContext) {
        //2.establish communication with MarketingFoundationSDK
        MarketingExtServiceProvider.getInstance().invokeJsApi(params, new MarketingJsBridgeCallback() {
            @Override
            public void onResult(JSONObject result) {
                //3.handle result
                Log.d("MarketingInvokePlugin", "#onResult result: " + result.toString());
                boolean isSuccess = result.getBoolean("success");
                if (result != null && isSuccess) {
                    String data = result.getString("data");
                } else {
                    String error = result.getString("error");
                }
                Log.d("MarketingInvokePlugin", "#onResult result: " + result.toString());
            }
        });
        return true;
    }
} 

Step 7: OAuth

Alipay+ SDK container

Maintain the same set of API protocols as the container, no need to implement here

Non-Alipay+ SDK container

This only needs to be implemented when it is not a Alipay+ SDK container

Request parameters

Field	Data type	Description	Required
clientId	String	The unique ID that is assigned by Mini Program Platform to identify a mini program.	Yes
scopes	Set<String>	Scope of Authorization	Yes
extendedInfo	Map<String, String>	An extended attribute that is used to provide additional information if necessary.	No

Example:

copy
// 1.Register OAuthServiceImpl 
//Tips: You can put OAuthServiceImpl and DeeplinkServiceImpl in the same ArrayList ,then register together
    List<Class<?>> serviceList = new ArrayList<>();
    serviceList.add(OAuthServiceImpl.class);
    PromoManager.getInstance().registerServices(serviceList);

//2.Implementing the MarketingFoundationOAuthProtocol
public class OAuthServiceImpl implements MarketingFoundationOAuthProtocol {
    public void getAuthCode(String clientId, Set<String> scopes, Map<String, String> extendedInfo, Callback callback) {
        // 3.Request authCode from the server
           ...
        // 4.handle result and callback
         callback.onResult();
    }
}

Step 8: Deeplink

Alipay+ SDK container

Maintain the same set of API protocols as the container, no need to implement here

Non-Alipay+ SDK container

This only needs to be implemented when it is not a Alipay+ SDK container

Input parameters

Parameter	Data type	Description
sceneCode	String	The scene code that presents a scene, such as MINI_PROGRAM and WEB_PAGE
params	Map<String, String>	Jump parameters, such as url, appid, etc.

Example:

copy
// 1.Register DeeplinkServiceImpl;
//Tips: you can put OAuthServiceImpl and DeeplinkServiceImpl in the same ArrayList ,then register together
    List<Class<?>> serviceList = new ArrayList<>();
    serviceList.add(DeeplinkServiceImpl.class);
    PromoManager.getInstance().registerServices(serviceList);


// 2.Implementing MarketingFoundationDeeplinkProtocol
public class DeeplinkServiceImpl implements MarketingFoundationDeeplinkProtocol {

    @Override
    public void open(@NonNull String sceneCode, @NonNull Map<String, String> map, RouterCallback callback) {

        if (TextUtils.equals(sceneCode,MARKETING_SCENE_WEB_PAGE)) {
            // Jump to webview
            callback.result();
        }else if(TextUtils.equals(sceneCode,MARKETING_SCENE_MINI_PROGRAM)) {
            // Jump Miniprogram  
            callback.result();
        }else {
            //No change type found
            callback.result();
          
        }
    }
}

iOS

Step 1：Add Rewards SDK to your project

1). Add the CDN source to your Podfile (usually at the top of your Podfile):

Podfile：https://guides.cocoapods.org/syntax/podfile.html

copy
source 'https://globaltech.alipay.com/api/v1/file/common/2017062215370883/minisdk'

Only the authorized machines can access our Cocoapods source. To make your machine authorized, simply add the configuration below to your .netrc file. (The .netrc file locates at your $HOME dir. Create one if it didn't exist.)

copy
machine globaltech.alipay.com
login LOGIN_ACCOUNT
password PASSWORD

2). Then, add the following pods to your Podfile

copy
# Required, Marketing Basic Library
pod 'IAPMarketing', 'LATEST_VERSION'
# Optional. Non-Alipay+ SDK containers need to be added, but Alipay+ SDK container does not need to be added
pod 'IAPMarketingFoundation', 'LATEST_VERSION'

Now you can run the pod install command in your project to let Cocoapods download the SDK and its dependencies.

Step 2：Initialize rewards

copy
import IAPMarketing

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // init A+ marketing module，Need to be placed after initializing the container
    let marketingConfig = PromoGlobalConfig()
    // The build environment must be configured as PROD
    marketingConfig.envType = .dev
    PromoContentManager.shared().setup(marketingConfig)

    return true
}

Step 3：Config JSAPI

Alipay+ SDK container

1): configure the JSAPI plist file

To configure the JSAPI plist file, add it to the project first. If a file already exists, configure it to record the information of JSAPI classes. In the plist file, add contents inside the <plist> tag with the following sample code:

copy
<key>JsApiRuntime</key>
<dict>
  <key>JsApis</key>
  <array>
    <dict>
      <key>name</key>
      <string>IAPMarketingJsApiHandle</string>
      <key>jsApi</key>
      <string>marketingInvoke</string>
    </dict>
  </array>
</dict>

2): Register the JSAPI to SDK

copy
let configuration = GRVConfiguration()
grvConfig.plistFilePathForExtraPlugins = Bundle.main.path(forResource: "FILE_NAME", ofType: "plist")!

Non-Alipay+ SDK container

1): Users are required to register Non-Alipay+ SDK container's jspai

2): Establish communication between container jsapi and IAPMarketingFoundationSDK，You need to establish communication as a middleman in the registered jsapi callback

Example:

copy
/// This is the callback you register with jsapi
- (void)handler:(NSDictionary *)data context:(RVKContext *)context callback:(RVKJsApiResponseCallbackBlock)callback {
    
    // Pass in the input parameter data of jsapi and call it back through jsapi after execution
    IAPMarketingFoundationProvider.sharedManager().handler(data) { response in
                                                                  
        // Return results
        callback(response)
    }    
}

Step 4：Add a New Configuration File

Please make sure the file is added to the main project
Contact the point of contact to provide the file

Add a new configuration file named rewards_widget_config.json and place it in the path: App/.

copy
{
    "auth": {
        "type": "mini-program", // environment type
        "clientId": "xxx",          // pass it to merchant as clientId/authClientId and get the auth code
        "scope": "auth_base",   // usually it's auth_base, it means only get user Id
        "mpContext": {                  // mpContext is required only when the type is miniprogram.
          "appId": "xxx",           // mini-app ID
          "merchantId": "xxx",  // merchant ID provider from mini-program platform, check this: https://yuque.antfin-inc.com/ac/xbggo2/imno85pm4or4hfzz#BVbGs
          "name": "xxxx",           // mini-app name
          "logo": "xxx",                // mini-app logo
          "desc": "xxx",                // mini-app desc
          "deployVersion": "xxx",   // mini-app version, you can get it from platform. like: v3.47.807
          "developerVersion": "xxx" // mini-app version of development stage, you can get it from IDE. like: v3.47.807.1728550147
        }
    },
    "rpc":{
          "appId": "MY_APP_ID",
          "gatewayUrl": {
              "dev": "DEV_GATEWAY_URL",   // dev gateway address
              "sit": "SIT_GATEWAY_URL",   // sit gateway address
              "pre": "PRE_GATEWAY_URL",   // pre gateway address
              "prod": "PROD_GATEWAY_URL"  // prod gateway address
          }
    },
    adapter:{
        "type":"XXX"  // adapter type
    }
}

Step 5: Clear login state

This function is called during logout to clear the user cache and reset the login status. If this function is not configured, it may result in an abnormal contract status, and the data loaded will still be associated with the previous user

copy
PromoContentManager.shared().clear()

Step 6: OAuth

Alipay+ SDK container

Maintain the same set of API protocols as the container, no need to implement here

Non-Alipay+ SDK container

This only needs to be implemented when it is not a Alipay+ SDK container

Request parameters

Field	Data type	Description	Required
clientId	String	The unique ID that is assigned by Mini Program Platform to identify a mini program.	Yes
scopes	Set<String>	Scope of Authorization	Yes
extendedInfo	Dictionary<String, String>	An extended attribute that is used to provide additional information if necessary.	No

Example:

copy
import IAPMarketingFoundation

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // Registering an OAuth delegate
    IAPMarketingFoundationProvider.sharedManager().oauthProvider = self
    return true
}

func getAuthCode(_ clientId: String, scopes: Set<String>, extendedInfo: [AnyHashable : Any], complete: @escaping (String?, String?) -> Void) {
        
   // 1.Request authCode from the server
        ...
    
   // 2.After the request is successful
   if (complete) {
      complete(authCode,errorMessage)
   }
}

Step 7: Deeplink

Alipay+ SDK container

Maintain the same set of API protocols as the container, no need to implement here

Non-Alipay+ SDK container

This only needs to be implemented when it is not a Alipay+ SDK container

Input parameters

Parameter	Data type	Description
sceneCode	String	The scene code that presents a scene, such as MINI_PROGRAM and WEB_PAGE
params	Map<String, String>	Jump parameters, such as url, appid, etc.

Example:

copy
import IAPMarketingFoundation


func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // Registering an deeplink delegate
    IAPMarketingFoundationProvider.sharedManager().deeplinkProvider = self
    return true
}

func open(withSceneCode sceneCode: String, params: [AnyHashable : Any], complete: @escaping (Bool, String?) -> Void) {
     
    /* 
        MARKETING_SCENE_WEB_PAGE Jump to webview
        MARKETING_SCENE_MINI_PROGRAM Jump Miniprogram 
    */
    if sceneCode == MARKETING_SCENE_WEB_PAGE {
      // Jump to webview
      
      if(complete){
        // Returns true if successful, false if failed and an error message
        complete(true,errorMessage)
      }
    }else if sceneCode == MARKETING_SCENE_MINI_PROGRAM {
      // Jump Miniprogram  
           
      if(complete){
        // Returns true if successful, false if failed and an error message
        complete(true,errorMessage)
      }
    }else {
    
        if(complete){
        complete(false,"No change type found")
      }
    }
}